1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# 接口名

## 接口协议：http / https

## 接口地址：写明需要调用的地址或 IP

## 接口端口：服务开启的端口号

## 目录（自动生成）

[TOC]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45

## 1. 简单描述接口

### 接口功能

> 描述这个接口是干什么用的，基本逻辑是什么

### URL

> 接口调用地址，例：`/api/rest/wasteMap/entInfo/getEntInfoById`

### 支持格式

> `json` / `html` / `xml`

### HTTP 请求方式

> `GET` / `POST` / `PUT` / `DELETE`

### 请求参数

| 参数 | 必选 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| id | 是 | string | 实体唯一标识 |
| name | 否 | string | 名称（模糊匹配） |

### 返回字段

| 返回字段 | 字段类型 | 说明 |
| :--- | :--- | :--- |
| code | int | 状态码，200=成功 |
| msg | string | 提示信息 |
| data | object | 业务数据 |
| data.id | string | 实体 ID |
| data.name | string | 实体名称 |

### 接口示例

> 调用地址：`http://api.example.com:8080/api/rest/...`

#### 请求参数

```json
{
  "id": "10001"
}

1
2
3
4
5
6
7
8

{
  "code": 200,
  "msg": "成功",
  "data": {
    "id": "10001",
    "name": "示例"
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53

### 1.3 完整示例

```markdown
# 危险废物地图 - 企业详情查询

## 接口协议：https

## 接口地址：api.example.com

## 接口端口：443

## 1. 简单描述接口

### 接口功能

> 根据企业 ID 查询企业基本信息、许可证信息、危废产生量

### URL

> `/api/rest/wasteMap/entInfo/getEntInfoById`

### 支持格式

> json

### HTTP 请求方式

> GET

### 请求参数

| 参数 | 必选 | 类型 | 说明 |
| :--- | :--- | :--- | :--- |
| entId | 是 | string | 企业 ID |

### 返回字段

| 返回字段 | 字段类型 | 说明 |
| :--- | :--- | :--- |
| code | int | 状态码 |
| msg | string | 描述 |
| data | object | 企业信息 |
| data.entName | string | 企业名称 |
| data.legalPerson | string | 法人 |
| data.address | string | 地址 |
| data.licenses | array | 许可证列表 |

### 接口示例

> 地址：`https://api.example.com/api/rest/wasteMap/entInfo/getEntInfoById?entId=10001`

#### 请求 Headers

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

#### 返回结果

```json
{
  "code": 200,
  "msg": "成功",
  "data": {
    "entName": "某环保科技公司",
    "legalPerson": "张三",
    "address": "江苏省南京市江宁区...",
    "licenses": [
      {
        "licNo": "HW-2024-001",
        "validUntil": "2027-12-31"
      }
    ]
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

## 二、接口文档工具链

### 2.1 OpenAPI 3.0（Swagger）

2015 年 Swagger 规范被 SmartBear 捐给 Linux 基金会，演化为 **OpenAPI 3.0**——机器可读的接口定义标准。

```yaml
# openapi.yaml
openapi: 3.0.0
info:
  title: 示例 API
  version: 1.0.0
  description: 危险废物地图服务
servers:
  - url: https://api.example.com
paths:
  /api/rest/wasteMap/entInfo/getEntInfoById:
    get:
      summary: 查询企业详情
      parameters:
        - name: entId
          in: query
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntInfo'
components:
  schemas:
    EntInfo:
      type: object
      properties:
        entName:
          type: string
        legalPerson:
          type: string

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# Git 仓库结构
docs/
├── api/
│   ├── openapi.yaml      # 接口定义
│   ├── errors.md         # 错误码字典
│   └── auth.md           # 鉴权说明
├── guides/
│   ├── quickstart.md
│   └── best-practices.md
└── README.md

1
2
3
4
5
6
7
8
9

// Razor Page
@page
@model IndexModel
@{
    ViewData["Title"] = "首页";
}

<h1>@Model.Greeting</h1>
<p>当前时间：@DateTime.Now</p>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

// .NET MAUI
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
    }

    void OnCounterClicked(object sender, EventArgs e)
    {
        count++;
        CounterLabel.Text = $"点击 {count} 次";
    }
}

1
2
3
4
5

# 5MB 镜像级别
FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine
WORKDIR /app
COPY --from=build /app/publish .
ENTRYPOINT ["dotnet", "MyService.dll"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

// Azure Functions 写法（无服务器）
public class HttpExample
{
    [Function("HttpExample")]
    public async Task<HttpResponseData> Run(
        [HttpTrigger(AuthorizationLevel.Function, "get", "post")] HttpRequestData req)
    {
        var response = req.CreateResponse(HttpStatusCode.OK);
        await response.WriteStringAsync("Hello from Azure Functions!");
        return response;
    }
}

1
2
3
4
5
6

// 训练一个情感分析模型
var mlContext = new MLContext();
var data = mlContext.Data.LoadFromTextFile<SentimentData>("sentiment.csv", hasHeader: true);
var pipeline = mlContext.Transforms.Text.FeaturizeText("Features", "Text")
    .Append(mlContext.BinaryClassification.Trainers.SdcaLogisticRegression());
var model = pipeline.Fit(data);

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21

新项目，应该选什么 .NET？
│
├─ Web / 微服务？
│   ├─ Windows only + 老系统集成 → ASP.NET (.NET Framework 4.8)
│   └─ 跨平台 / 容器 / 云原生 → ASP.NET Core (.NET 8 / 9)
│
├─ 桌面？
│   ├─ 内部工具 / Windows only → WPF / WinForms
│   ├─ 现代 Windows UI → WinUI 3
│   └─ 跨平台桌面 → Avalonia / .NET MAUI
│
├─ 移动？
│   ├─ iOS / Android / Windows 跨平台 → .NET MAUI
│   └─ Unity 游戏 → Unity + C#
│
├─ 嵌入式 / IoT？
│   ├─ 资源极受限（< 256KB RAM）→ C / C++
│   └─ STM32 / ESP32 → .NET nanoFramework
│
└─ ML？
    └─ ML.NET / 调 ONNX / 调 TensorFlow.NET