---
tags: []
aliases:
  - 🔌 AI 辅助 API 定义方法论 (v1.0)
date created: 星期日, 十二月 7日 2025, 11:43:04 晚上
date modified: 星期日, 十二月 7日 2025, 11:44:30 晚上
---

# 🔌 AI 辅助 API 定义方法论 (v1.0)

**核心理念:**

1. **DTO 先行:** 先定义输入 (Request) 和输出 (Response) 的数据结构，再写业务逻辑。
2. **注释即文档:** 利用 AI 自动生成繁琐的 Swagger 注释 (`@Summary`, `@Param`…)。
3. **契约可视化:** 在写第一行逻辑代码前，先能在 Swagger UI 上看到接口定义。

---

## 阶段一：API 资源设计 (Design)

**目的:** 确定 URL 路径、HTTP 方法和 JSON 数据结构，确保符合 RESTful 规范。

### 🤖 通用 Prompt (复制使用)

```Markdown
你现在是我的 **API 架构师**。
我们已经完成了数据库设计，现在需要设计 `{业务模块}` (例如: User) 的 API 接口。

**输入上下文:**
1.  **业务实体:** `{粘贴 User 的 Entity 代码或 SQL}`
2.  **功能需求:** 注册、登录、获取个人资料、更新资料。

**请输出 API 设计方案 (表格形式):**
1.  **Method:** GET/POST/PUT/PATCH/DELETE
2.  **Path:** URL 路径 (使用 RESTful 风格, 如 `/api/v1/users/:id`)
3.  **Request Body:** 关键字段 (JSON 示例)
4.  **Response:** 成功返回的数据结构 (JSON 示例)

**设计原则:**
- 使用统一的响应信封: `{ "code": 200, "msg": "success", "data": ... }`
- 更新操作区分 PUT (全量) 和 PATCH (局部)。
- 敏感字段 (密码) 绝对不能出现在 Response 中。
```

---

## 阶段二：生成 DTO 结构体 (Contract Definition)

**目的:** 将 JSON 设计转化为 Go 结构体。这是前后端交互的**法律条文**。

**工程位置:** `internal/api/request/` (入参) 和 `internal/api/response/` (出参)。

### 🤖 通用 Prompt (复制使用)

```Markdown
设计确认通过。请基于上述设计，生成 Go 语言的 **DTO (Data Transfer Object) 结构体**。

**技术约束:**
1.  使用 `gin` 的 binding 标签进行参数校验 (如 `binding:"required,email"`).
2.  使用 `json` 标签定义字段名 (camelCase).
3.  **分离 Request 和 Response:** 不要直接复用数据库 Entity，必须定义独立的 DTO。

**输出代码要求:**
- `UserRegisterReq` (包含 Email, Password, ConfirmPassword)
- `UserLoginReq`
- `UserProfileResp` (不含密码，转换时间格式)

请直接输出 Go 代码，放在 package `user_dto` 下。
```

---

## 阶段三：生成 Handler 骨架与 Swagger 注释 (Implementation Skeleton)

**目的:** 这是一个“体力活”。AI 最擅长帮我们要写几十行的 Swagger 注释。

**工程位置:** `internal/user/handler.go`

### 🤖 通用 Prompt (复制使用)

```Markdown
现在请生成 Gin Handler 的**代码骨架**，并附带完整的 **Swagger 注释**。

**输入:**
DTO 结构体已定义: `UserRegisterReq`, `UserProfileResp`...

**输出要求:**
1.  **Swagger 注释:** 必须包含 `@Summary`, `@Tags`, `@Accept json`, `@Produce json`, `@Param`, `@Success`, `@Router`。
2.  **Handler 签名:** 接收 `*gin.Context`。
3.  **参数绑定:** 在 Handler 内部生成 `ShouldBindJSON` 代码块。
4.  **占位返回:** 暂时直接返回 Mock 数据或 `http.StatusOK`，**不要写具体的 Service 业务逻辑**。

**示例注释格式:**
// Register
// @Summary 用户注册
// @Tags User
// @Accept json
// @Produce json
// @Param request body user_dto.UserRegisterReq true "注册信息"
// @Success 200 {object} app.Result{data=user_dto.UserProfileResp}
// @Router /api/v1/auth/register [post]
func (h *UserHandler) Register(c *gin.Context) { ... }
```

---

## 🏗️ 工程落地操作指南 (How to Execute)

### 1. 文件安放位置

不要乱放，严格遵守目录结构：

```Plaintext
internal/
├── api/                    # [Contract Layer] 存放 DTO
│   ├── request/            # 入参结构体
│   │   └── user_req.go
│   └── response/           # 出参结构体
│       └── user_resp.go
└── user/                   # [Domain Layer]
    └── handler.go          # 控制器 (含 Swagger 注释)
```

### 2. 实操步骤 (SOP)

#### Step 1: 定义 DTO (The Contract)

- 运行阶段二的 Prompt。
- 将代码复制到 `internal/api/request/user_req.go`。
- **这一步完成了，就代表你和前端的接口契约签好了。**

#### Step 2: 编写 Handler 骨架 (The Skeleton)

- 运行阶段三的 Prompt。
- 将代码复制到 `internal/user/handler.go`。
- 确保此时代码能编译通过（缺少 Service 调用没关系，先留空）。

#### Step 3: 生成 Swagger 文档 (Generate)

这是验证的关键一步。我们需要使用 `swag` 工具扫描你的注释并生成 JSON 文档。

**在终端执行:**

```Bash
swag init -g cmd/server/main.go -o docs
```

_(注意: `-g` 指向你的 main 函数入口，swag 会从那里开始递归扫描)_

#### Step 4: 启动服务并验证 (Verify)

- 运行 `go run cmd/server/main.go`。
- 打开浏览器访问 `http://localhost:8080/swagger/index.html`。
- **你看到的界面，就是你刚刚定义的“接口合同”。**

---

## 💡 常见问题与技巧

**Q: 为什么不直接用 Entity 作为 Response？**

- **A:** **千万别这么做。** Entity 包含 `password_hash`，包含 `deleted_at`，这些都不该给前端。DTO 让你有精准控制返回字段的权利。

**Q: Swagger 注释太难写了，容易写错格式。**

- **A:** 这就是为什么要用 AI 的原因。**永远不要手写 Swagger 注释**。把 Handler 代码发给 AI，对它说：“_请帮我补全 Swagger 注释，参数是 X，返回值是 Y_”。

**Q: 接口变了怎么办？**

- **A:**
    
    1. 修改 DTO (Go Struct)。
    2. 让 AI 更新 Handler 里的 Swagger 注释。
    3. 运行 `swag init`。
    4. 文档自动更新。

---

**总结你的下一步行动:**

1. **DTO 设计:** 使用 Prompt 生成 `User` 相关的 Request/Response 结构体。
2. **骨架生成:** 使用 Prompt 生成带有 Swagger 注释的 `UserHandler`。
3. **文档验证:** 运行 `swag init` 并在浏览器中确认接口文档无误。