Inbox/Go项目实战/02_接口设计/AI 辅助 API 定义方法论 (v1.0).md

tags, aliases, date created, date modified

tags	aliases	date created	date modified
	🔌 AI 辅助 API 定义方法论 (v1.0)	星期日, 十二月 7日 2025, 11:43:04 晚上	星期日, 十二月 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 (复制使用)

你现在是我的 **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 (复制使用)

设计确认通过。请基于上述设计，生成 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 (复制使用)

现在请生成 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. 文件安放位置

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

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 文档。

在终端执行:

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 并在浏览器中确认接口文档无误。