API
设计博客文章接口
设计文章列表、文章详情、新增文章、编辑文章、删除文章接口，包含路径、方法、参数、响应和错误码。
产出物一份可给 AI 直接生成代码的 API 文档。
Checklist
阶段任务
- 掌握 GET、POST、PUT、PATCH、DELETE 的使用场景
- 掌握 200、201、204、400、401、403、404、409、500、502 等常见状态码
- 区分 query、params、body、headers
- 理解 Cookie、Authorization、Content-Type、Accept 等常见请求头
- 设计统一响应格式和错误响应格式
- 设计分页、排序、筛选、搜索接口
- 理解接口幂等、重复提交、批量操作和软删除的基本设计
- 理解 OpenAPI、Mock、接口版本和向后兼容
- 用 Apifox、Postman 或 curl 调试一个接口
- 写出前端请求封装需要依赖的状态码、错误码和字段约定
Labs
建议练习
排错
用 curl 调试接口
使用 curl 分别发送 GET 和 POST 请求，观察请求体、响应体和状态码。
产出物记录至少 3 条可复用 curl 命令。
API
设计错误响应约定
为参数错误、未登录、无权限、资源不存在、数据冲突、服务器异常设计统一错误响应。
产出物一份前端 request 封装可直接使用的错误码和提示规则。
API
生成 Mock 和 OpenAPI 草案
把博客文章接口整理成 OpenAPI 风格结构，并用 Apifox 或 Postman 创建 Mock 数据。
产出物一个可被前端联调使用的接口集合。
Daily Plan
每日安排
Day 1
HTTP 请求与响应
把方法、路径、参数、请求头、状态码和 JSON 响应放到一张接口契约里。
- 用浏览器 Network 观察一个真实 API 请求
- 记录 URL、method、query、headers、request payload、response、status code
- 用 curl 复现同一个请求
- 整理 GET、POST、PUT、PATCH、DELETE 的使用边界
当天产出一份 HTTP 请求解剖笔记和 3 条 curl 命令。
Day 2
设计 CRUD 接口契约
把前端页面需要的数据转成后端能实现的接口文档。
- 为文章列表、详情、新增、编辑、删除设计接口
- 补齐分页、筛选、排序、搜索参数
- 定义统一成功响应和错误响应
- 列出每个接口的权限要求和常见错误码
当天产出一份文章管理 API 文档。
Day 3
联调、Mock 与错误处理
练习接口还没写完时如何让前端继续开发，接口出错时如何定位。
- 用 Apifox 或 Postman 创建接口集合
- 为列表和详情接口创建 Mock 响应
- 模拟 400、401、403、404、409、500 响应
- 设计前端 request 封装需要的错误处理规则
当天产出一套可调试的接口集合和前端错误处理约定。
Day 4
接口质量检查
从真实项目角度检查接口是否稳定、可扩展、方便前端使用。
- 检查接口是否存在字段命名不统一、分页不完整、状态码滥用
- 为新增、删除、支付类操作思考幂等和重复提交
- 确认日期、金额、枚举、空值的返回格式
- 让 AI Review 接口文档并按严重程度列问题
当天产出一份 API Review 清单。
Knowledge
知识点解释
API 是前后端协作的契约。接口越清晰，AI 生成的后端越可靠。
RESTful API
围绕资源设计接口，用 HTTP 方法表达动作。
前端类比：类似前端围绕页面资源组织状态和操作，而不是把所有动作写成一个函数。
状态码
HTTP 层面的结果标识，告诉调用方请求是成功、未授权、找不到还是服务器错误。
前端类比：类似 Promise 的 resolve/reject，但状态码更细。
统一响应格式
让所有接口返回相似结构，方便前端统一处理成功、错误和提示。
前端类比：类似前端 request 封装统一处理 code、message、data。
接口幂等
同一个请求重复执行多次，结果仍然可控，常用于删除、支付、提交订单等场景。
前端类比：类似按钮防重复点击，但后端必须自己保证重复请求不会造成脏数据。
OpenAPI
一种标准化描述接口路径、参数、响应和 schema 的规范，方便生成文档和客户端代码。
前端类比：类似把 API 类型和说明写成机器可读的契约。
Mock
在后端未完成时用模拟数据满足前端联调，减少等待。
前端类比：类似前端用假数据先开发页面，但要尽量贴近真实接口格式。
常见坑点
- 不要把所有接口都设计成 POST
- 不要只返回字符串，前端需要稳定的 JSON 结构
- 权限错误用 401 或 403，不要都返回 500
- 分页接口要明确 page、pageSize、total、list
- 不要让 code 和 HTTP status 表达互相矛盾的结果
- 日期、金额、枚举、空数组、空对象要提前约定格式
- 删除接口要确认是物理删除还是软删除
Prompts
AI 协作提示词
生成接口文档
请帮我设计一组博客文章管理 API。要求包含文章列表、文章详情、新增文章、编辑文章、删除文章。请输出接口路径、请求方法、请求参数、响应 JSON、常见错误码。我是前端开发，请额外说明每个接口在前端如何调用。接口联调排查
我的前端调用接口失败。请求地址是【填写地址】，请求方法是【填写方法】，请求参数是【填写参数】，响应状态码是【填写状态码】，响应内容是【填写响应】。请帮我判断是前端参数问题、跨域问题、鉴权问题还是后端错误。API Review
请 Review 下面这份 API 文档。重点检查 HTTP 方法是否合理、路径命名是否一致、分页和搜索是否完整、状态码和业务错误码是否清晰、权限要求是否明确、是否存在幂等和重复提交风险、前端调用是否方便。请按严重程度列出问题和修改建议。Acceptance
验收标准
- 能写出一个 CRUD 模块接口文档
- 能根据状态码判断常见问题方向
- 能用工具独立发送请求并查看响应
- 能设计分页、筛选、排序、搜索和错误响应
- 能把接口需求描述给 AI 并获得可实现的代码
- 能让 AI Review 接口契约，而不是只让它写接口代码
Resources
推荐资源
Progress