easy-vibe API 设计实战RESTful 命名、状态码、错误处理与响应结构规范【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe本文基于 easy-vibe 课程附录《服务端与后端》中的 API 设计章节docs/ar-sa/appendix/4-server-and-backend/api-design.md中文版见 docs/zh-cn/appendix/4-server-and-backend/api-design.md系统讲解前后端如何约定一套清晰的“对话规则”从 RESTful URL 命名、HTTP 方法选择、状态码分类到错误响应设计、接口版本控制与统一响应结构并给出可直接套用的电商 API 设计实例与 AI 辅助设计的提示词模板。读完后你能独立设计出一套命名一致、错误可诊断、可平滑升级版本的 RESTful API。1. 为什么需要 API 设计规范三个典型“梦魇”场景课程文档开篇用三个反面场景说明了缺少统一规范时的协作困境场景一接口命名风格混乱GET /getUserData GET /fetchUserInfo GET /queryUserById GET /users/query四个接口功能相同命名风格却完全不同新成员无法判断该调用哪一个。场景二错误处理方式互相矛盾// 有人直接返回 HTTP 状态码 HTTP/1.1 404 Not Found // 有人返回 200 业务 code HTTP/1.1 200 OK { code: 404, message: 用户不存在 } // 有人直接抛出异常文本 HTTP/1.1 200 OK { error: 出错了 }前端无法统一判断请求是否成功。场景三每个接口的响应结构都不一样// 接口 A { data: { ... } } // 接口 B { result: { ... } } // 接口 C { content: { ... } }返回字段名各不相同前端被迫为每个接口单独写解析逻辑。文档的核心论点是好的 API 设计就像餐厅的点餐系统——菜单清晰API 文档、流程有序统一协议、出错有提示结构化错误响应它解决的是“对话规则”问题。2. API 概览餐厅类比与一次完整的请求周期APIApplication Programming Interface应用程序编程接口是“程序之间的对话协议”。文档用一个餐厅类比建立直观理解餐厅角色对应概念描述菜单API 文档告诉你有哪些“菜品”可以点服务员HTTP 协议统一的“对话方式”厨房服务器根据“订单”处理请求上菜响应把结果交回给“顾客”关于一次完整的 API 请求/响应周期easy-vibe 网站提供了一个可交互的终端演示组件读者可以在页面中点击按钮观察请求从客户端发出、到达服务器、再返回响应的全过程。该演示的实现位于主题组件目录 docs/.vitepress/theme/components/appendix/api-design/ApiRequestDemo.vue左侧模拟终端逐行打印请求与响应右侧用流程图高亮“客户端 → 服务器”两个阶段的脉冲动画与正文讲解互为印证。3. API 设计风格RPC / REST / GraphQL / gRPC 四选一在深入 RESTful 细节之前文档先梳理了四种主流 API 设计风格并配有交互式对比组件实现见 ApiStyleCompare.vue可通过 组件国际化对照表 查看其在多语言版本中的挂载方式。3.1 REST 与 RESTful 的区别很多人混淆这两个概念概念含义描述REST架构风格Roy Fielding 提出的设计哲学包含一组约束RESTful符合 REST 风格形容词表示 API 设计遵循了 REST 原则类比REST 如同“简约主义”——是一种设计哲学RESTful API 如同“简约风装修的房间”——是这种哲学的具体落地。REST 的六大约束约束描述客户端-服务器分离前后端独立开发接口解耦无状态每个请求携带全部必要信息服务器不保存会话状态可缓存响应需明确是否可缓存以提升性能统一接口使用标准的 HTTP 方法和状态码分层系统客户端无需感知自己连接的是服务器哪一层代码按需加载可选服务器可扩展客户端功能文档给出的“为什么 REST 最常用”的理由有四条HTTP 协议本身即体现 REST 思想学习成本低工具、框架与文档生态成熟通用性强任何语言任何平台都能调用GET 请求天然可缓存对 CDN 友好。4. RESTful 设计让 URL 会说话**REST表述性状态转移**的核心思想是把网络上的事物抽象为“资源”Resource用 URL 标识资源用 HTTP 方法操作资源。4.1 仓库类比仓库概念REST 对应示例货架地址URL/users、/orders操作方式HTTP 方法GET查看、POST放入货物资源用户数据、订单数据核心原则URL 是名词不是动词。4.2 URL 设计规则规则错误示例正确示例说明用名词不用动词/getUsers/usersURL 表示资源HTTP 方法表示操作使用复数形式/user/users统一复数风格小写字母 连字符/UserProfiles/user-profilesURL 区分大小写统一风格最安全避免过深嵌套/a/b/c/d/e/a/b/c最多 3 层用查询参数过滤/products/phone/5000/products?catphone过滤条件走?参数4.3 HTTP 方法选择方法用途幂等性安全性典型场景GET获取资源是是列表查询、详情展示POST创建资源否否新增用户、提交订单PUT完整更新是否整体替换用户资料PATCH部分更新否否仅修改昵称DELETE删除资源是否删除用户、取消订单其中“幂等性”Idempotency指执行多次操作得到相同结果GET/PUT/DELETE 属于幂等操作点击 10 次与 1 次结果一致而 POST 不幂等点击 10 次可能创建 10 个订单。文档给出的对策是为 POST 操作引入唯一标识幂等键做去重校验。5. 状态码让错误“开口说话”HTTP 状态码是服务器向客户端告知“发生了什么”的标准方式。文档给出了分类总表分类含义常见状态码2xx成功200 OK、201 Created、204 No Content3xx重定向301 永久移动、304 未修改4xx客户端错误400 参数错误、401 未认证、404 未找到5xx服务端错误500 内部错误、503 服务不可用页面中还有一个状态码含义演示组件StatusCodeDemo.vue可点击触发各常见状态码并查看其含义适合作为记忆辅助。6. 错误处理优雅地“拒绝”好的错误处理让客户端能“凭状态码就知道发生了什么”而不是靠猜。文档列出了三个高频陷阱陷阱一所有错误都返回 200// ❌ 错误做法 HTTP/1.1 200 OK { error: 出错了 }问题在于缓存层会把这个“成功”响应存下来监控系统也无法发现异常。陷阱二错误信息过于笼统// ❌ 错误做法 HTTP/1.1 400 Bad Request { message: 参数错误 }问题在于客户端不知道是哪个参数错、为什么错。陷阱三泄露敏感信息// ❌ 危险做法 HTTP/1.1 500 Internal Server Error { stack: at UserService.login..., sql: SELECT * FROM... }风险暴露了代码结构与数据库查询语句可被攻击者利用。仓库中对应的教学组件 ErrorHandlingDemo.vue 提供了“好/坏”错误响应设计的对比交互与上述三个陷阱形成正反对照。7. 版本控制API 的“向前兼容”动机假设你的应用有大量用户需要修改订单接口。若不做版本控制旧应用调用新接口会因字段缺失而崩溃。正确做法是让新旧版本并存/v1/orders—— 旧接口继续服务老应用/v2/orders—— 新接口承载新功能。三种版本控制策略对比策略示例优点缺点URL 路径/v1/users直观、易缓存URL 变长请求头Accept: vnd.api.v2jsonURL 干净不便于手工调试查询参数/users?version2简单标准化程度不足版本演进示例以用户与订单为例原文档位于 api-design.md 第 238 节接口v1旧v2新变更说明获取用户GET /v1/users返回name, emailGET /v2/users返回name, email, avatar, phone新增头像与手机号字段创建订单POST /v1/orders接收items[]POST /v2/orders接收items[], coupons[]新增优惠券支持批量操作无POST /v2/orders/batch新增批量创建接口版本控制最佳实践文档原文四条保持向后兼容v1 接口至少维护 6–12 个月给客户端留出升级时间文档同步更新每个版本维护独立的 API 文档下线预告提前公告 v1 的废弃时间引导用户迁移监控用量统计 v1 的调用量确认可以安全下线后再停服。8. 响应结构设计大厂规范借鉴响应结构是前后端协作的“数据契约”统一格式能显著降低沟通成本。文档先引用了响应结构演示组件ResponseStructureDemo.vue再逐一拆解业界规范Google API 设计规范要求所有 API 错误响应包含统一的error结构{ error: { code: 429, message: 资源不足请稍后重试, status: RESOURCE_EXHAUSTED, details: [ { type: type.googleapis.com/google.rpc.ErrorInfo, reason: RESOURCE_AVAILABILITY, domain: compute.googleapis.com, metadata: { zone: us-east1-a, service: compute } } ] } }要点details中必须包含机器可读的错误标识ErrorInfomessage面向开发者简洁描述问题与解决办法details可携带本地化消息、帮助链接等扩展信息。Microsoft REST API 指南强调错误分类与响应头规范错误Error由客户端发送无效数据引起返回 4xx不影响 API 可用性故障Fault服务端无法正确处理有效请求返回 5xx影响可用性响应头DateRFC 5322 GMT 格式、Content-Type必须返回支持乐观并发控制的资源必须返回ETag。阿里巴巴 Java 开发手册给出了统一返回对象与错误码分段设计public class ResultT { private Integer code; private String message; private T data; private String requestId; }码段类型示例0成功01xxxx参数错误10001 必填参数缺失2xxxx业务错误20001 余额不足3xxxx认证错误30001 未登录5xxxx系统错误50001 数据库异常Stripe API 的错误响应设计得极为精细{ error: { type: card_error, code: card_declined, message: Your card was declined., param: number, decline_code: insufficient_funds, doc_url: https://stripe.com/docs/error-codes/card-declined } }设计亮点type区分错误大类api_error、card_error、invalid_request_errorparam精确指出哪个参数出错前端可直接定位到表单字段doc_url提供文档链接decline_code提供更细粒度的错误原因。JSON:API 规范是业内广泛采用的 JSON 响应标准{ data: { type: articles, id: 1, attributes: { title: JSON:API 规范详解 }, relationships: { author: { data: { type: users, id: 9 } } } }, included: [ { type: users, id: 9, attributes: { name: 张三 } } ] }核心设计data携带主资源必须包含type与idattributes存资源属性relationships描述资源关联included一次性返回关联数据避免重复请求。GitHub REST API则展示了面向开发者体验的设计成功响应中同时提供多种 URL 形态html_url、url便于不同场景使用错误响应附带documentation_url指向文档使用Link响应头实现分页导航。Twitter/X API v2采用简洁的dataincludes结构includes类似 JSON:API 的included支持?tweet.fieldscreated_at,public_metrics形式的字段选择分页使用next_token/previous_token。8.1 响应结构最佳实践汇总综合上述规范文档总结了响应结构设计的五条原则一致性优先所有接口使用同一响应结构前端可统一封装请求层机器可读错误码 原因码reason让程序能自动处理人类友好message清晰并给出解决建议可追踪request_id贯穿整个请求链路方便定位问题支持国际化通过 details 扩展翻译后的消息。data字段的设计规范与错误响应的进阶设计分别由 DataFieldDesignDemo.vue 和 ErrorResponseDesignDemo.vue 两个交互组件展开演示。9. 实战演练电商系统 API 完整设计文档给出的综合示例覆盖了用户、订单、产品三个模块原文见 api-design.md 第 8 节# 用户模块 GET /v1/users # 获取用户列表 POST /v1/users # 创建新用户 GET /v1/users/{id} # 获取用户详情 PUT /v1/users/{id} # 完整更新用户 PATCH /v1/users/{id} # 部分更新用户 DELETE /v1/users/{id} # 删除用户 # 订单模块 GET /v1/users/{id}/orders # 获取某用户的订单 POST /v1/orders # 创建订单 GET /v1/orders/{id} # 获取订单详情 PATCH /v1/orders/{id}/status # 更新订单状态 # 商品模块复杂过滤使用查询参数 GET /v1/products?categoryphoneprice_max5000sortprice_descpage1这段清单恰好是前述全部规则的落地URL 全为复数名词、版本前缀/v1/、方法语义正确完整更新用 PUT、状态变更用 PATCH、嵌套关系用户下的订单不超过 3 层、复杂过滤条件全部收敛到查询参数。10. 用 AI 辅助 API 设计提示词模板与注意事项easy-vibe 作为一门 AI 编程课程专门给出了“让 AI 按规范产出 API 设计”的完整工作流。10.1 提示词模板你是一名后端架构师精通 RESTful API 设计。请帮我设计一组 API 接口。 ## 业务背景 [描述你的业务场景比如电商系统、博客平台、任务管理等] ## 功能需求 [列出需要的功能模块比如 - 用户管理注册、登录、个人信息 - 订单管理创建订单、查询订单、取消订单 - 商品管理商品列表、商品详情、搜索] ## 设计要求 1. 遵循 RESTful 规范 2. URL 使用复数名词、小写 连字符 3. 正确使用 HTTP 方法GET/POST/PUT/PATCH/DELETE 4. 统一响应格式{ code, message, data, request_id } 5. 合理使用状态码 6. 版本控制URL 路径方式/v1/ ## 输出格式 请按以下格式输出 ### 接口清单 | 方法 | URL | 描述 | 请求体 | 响应体 | |------|-----|------|--------|--------| ### 请求/响应示例 [主要接口的详细示例] ### 状态码说明 [使用的状态码及其含义]模板的关键在于“明确的上下文 明确的约束条件”把命名规则、响应格式、版本策略全部写进提示词AI 的输出才稳定可控。10.2 应用示例电商订单 API输入提示词你是一名后端架构师精通 RESTful API 设计。请帮我设计一组电商订单系统的 API 接口。 ## 业务背景 一个 B2C 电商平台用户可以浏览商品、提交订单、查看订单状态。 ## 功能需求 - 订单模块创建订单、查询订单列表、查询订单详情、取消订单、支付订单 - 购物车模块添加商品、修改数量、删除商品、查看购物车 ## 设计要求 1. 遵循 RESTful 规范 2. URL 使用复数名词、小写 连字符 3. 正确使用 HTTP 方法 4. 统一响应格式 5. 版本控制/v1/AI 示例输出文档原文的接口清单方法URL描述POST/v1/orders创建订单GET/v1/orders查询订单列表GET/v1/orders/{id}查询订单详情PATCH/v1/orders/{id}/status更新订单状态取消/支付GET/v1/users/{id}/cart获取购物车POST/v1/users/{id}/cart/items添加商品到购物车PATCH/v1/users/{id}/cart/items/{itemId}修改购物车商品数量DELETE/v1/users/{id}/cart/items/{itemId}删除购物车商品10.3 AI 辅助设计的注意事项注意点说明提供完整上下文业务背景、用户角色、数据关系都要说清楚明确约束条件命名规则、版本策略、响应格式要提前定义迭代优化第一次输出未必完美追问细节、要求修改人工审核AI 生成内容需人工审查确保符合业务需求补充边界情况让 AI 考虑错误处理、权限控制、分页等边界情况文档还推荐了几条常用的追问话术“请为每个接口补充错误响应示例”“请考虑分页、排序和筛选参数”“请为接口补充权限控制说明”“请检查是否符合 RESTful 最佳实践”。11. 术语速查表文档最后附上术语速查表便于回顾术语英文解释APIApplication Programming Interface程序间的对话协议RESTRepresentational State Transfer架构风格用 URL 标识资源资源ResourceREST 架构中的基本对象有唯一标识URL幂等性Idempotency多次执行操作得到相同结果状态码Status CodeHTTP 协议定义响应状态的码版本控制Versioning让 API 新旧版本共存便于平滑升级请求体Request BodyPOST/PUT/PATCH 请求发送的数据响应体Response Body服务器返回的数据头部Header请求/响应的元数据如 Content-Type认证Authentication验证“你是谁”登录、Token授权Authorization验证“你能做什么”权限12. 延伸在 easy-vibe 仓库中继续学习本章的前置阅读是 API 入门篇 api-intro.md其配套演示组件ApiPlayground、HttpMethodsDemo、StatusCodeCategories 等位于 docs/.vitepress/theme/components/appendix/api-intro/ 目录同目录下的 auth-authorization.md 讲解认证与授权可与本文的术语表中“认证/授权”条目衔接阅读附录全部 9 章的导航入口在 docs/ar-sa/appendix/index.md中文版在 docs/zh-cn/appendix/index.md本仓库基于 VitePress 构建见 package.json 中vitepress依赖与dev脚本各语言版本文档zh-cn、en、ja-jp、ko-kr、de-de、fr-fr、es-es、vi-vn、zh-tw、ar-sa共享同一套 主题组件 与布局因此文中提到的交互演示组件在所有语言版本中行为一致。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 easy-vibe API 设计实战：RESTful 命名、状态码、错误处理与响应结构规范
easy-vibe API 设计实战RESTful 命名、状态码、错误处理与响应结构规范【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe本文基于 easy-vibe 课程附录《服务端与后端》中的 API 设计章节docs/ar-sa/appendix/4-server-and-backend/api-design.md中文版见 docs/zh-cn/appendix/4-server-and-backend/api-design.md系统讲解前后端如何约定一套清晰的“对话规则”从 RESTful URL 命名、HTTP 方法选择、状态码分类到错误响应设计、接口版本控制与统一响应结构并给出可直接套用的电商 API 设计实例与 AI 辅助设计的提示词模板。读完后你能独立设计出一套命名一致、错误可诊断、可平滑升级版本的 RESTful API。1. 为什么需要 API 设计规范三个典型“梦魇”场景课程文档开篇用三个反面场景说明了缺少统一规范时的协作困境场景一接口命名风格混乱GET /getUserData GET /fetchUserInfo GET /queryUserById GET /users/query四个接口功能相同命名风格却完全不同新成员无法判断该调用哪一个。场景二错误处理方式互相矛盾// 有人直接返回 HTTP 状态码 HTTP/1.1 404 Not Found // 有人返回 200 业务 code HTTP/1.1 200 OK { code: 404, message: 用户不存在 } // 有人直接抛出异常文本 HTTP/1.1 200 OK { error: 出错了 }前端无法统一判断请求是否成功。场景三每个接口的响应结构都不一样// 接口 A { data: { ... } } // 接口 B { result: { ... } } // 接口 C { content: { ... } }返回字段名各不相同前端被迫为每个接口单独写解析逻辑。文档的核心论点是好的 API 设计就像餐厅的点餐系统——菜单清晰API 文档、流程有序统一协议、出错有提示结构化错误响应它解决的是“对话规则”问题。2. API 概览餐厅类比与一次完整的请求周期APIApplication Programming Interface应用程序编程接口是“程序之间的对话协议”。文档用一个餐厅类比建立直观理解餐厅角色对应概念描述菜单API 文档告诉你有哪些“菜品”可以点服务员HTTP 协议统一的“对话方式”厨房服务器根据“订单”处理请求上菜响应把结果交回给“顾客”关于一次完整的 API 请求/响应周期easy-vibe 网站提供了一个可交互的终端演示组件读者可以在页面中点击按钮观察请求从客户端发出、到达服务器、再返回响应的全过程。该演示的实现位于主题组件目录 docs/.vitepress/theme/components/appendix/api-design/ApiRequestDemo.vue左侧模拟终端逐行打印请求与响应右侧用流程图高亮“客户端 → 服务器”两个阶段的脉冲动画与正文讲解互为印证。3. API 设计风格RPC / REST / GraphQL / gRPC 四选一在深入 RESTful 细节之前文档先梳理了四种主流 API 设计风格并配有交互式对比组件实现见 ApiStyleCompare.vue可通过 组件国际化对照表 查看其在多语言版本中的挂载方式。3.1 REST 与 RESTful 的区别很多人混淆这两个概念概念含义描述REST架构风格Roy Fielding 提出的设计哲学包含一组约束RESTful符合 REST 风格形容词表示 API 设计遵循了 REST 原则类比REST 如同“简约主义”——是一种设计哲学RESTful API 如同“简约风装修的房间”——是这种哲学的具体落地。REST 的六大约束约束描述客户端-服务器分离前后端独立开发接口解耦无状态每个请求携带全部必要信息服务器不保存会话状态可缓存响应需明确是否可缓存以提升性能统一接口使用标准的 HTTP 方法和状态码分层系统客户端无需感知自己连接的是服务器哪一层代码按需加载可选服务器可扩展客户端功能文档给出的“为什么 REST 最常用”的理由有四条HTTP 协议本身即体现 REST 思想学习成本低工具、框架与文档生态成熟通用性强任何语言任何平台都能调用GET 请求天然可缓存对 CDN 友好。4. RESTful 设计让 URL 会说话**REST表述性状态转移**的核心思想是把网络上的事物抽象为“资源”Resource用 URL 标识资源用 HTTP 方法操作资源。4.1 仓库类比仓库概念REST 对应示例货架地址URL/users、/orders操作方式HTTP 方法GET查看、POST放入货物资源用户数据、订单数据核心原则URL 是名词不是动词。4.2 URL 设计规则规则错误示例正确示例说明用名词不用动词/getUsers/usersURL 表示资源HTTP 方法表示操作使用复数形式/user/users统一复数风格小写字母 连字符/UserProfiles/user-profilesURL 区分大小写统一风格最安全避免过深嵌套/a/b/c/d/e/a/b/c最多 3 层用查询参数过滤/products/phone/5000/products?catphone过滤条件走?参数4.3 HTTP 方法选择方法用途幂等性安全性典型场景GET获取资源是是列表查询、详情展示POST创建资源否否新增用户、提交订单PUT完整更新是否整体替换用户资料PATCH部分更新否否仅修改昵称DELETE删除资源是否删除用户、取消订单其中“幂等性”Idempotency指执行多次操作得到相同结果GET/PUT/DELETE 属于幂等操作点击 10 次与 1 次结果一致而 POST 不幂等点击 10 次可能创建 10 个订单。文档给出的对策是为 POST 操作引入唯一标识幂等键做去重校验。5. 状态码让错误“开口说话”HTTP 状态码是服务器向客户端告知“发生了什么”的标准方式。文档给出了分类总表分类含义常见状态码2xx成功200 OK、201 Created、204 No Content3xx重定向301 永久移动、304 未修改4xx客户端错误400 参数错误、401 未认证、404 未找到5xx服务端错误500 内部错误、503 服务不可用页面中还有一个状态码含义演示组件StatusCodeDemo.vue可点击触发各常见状态码并查看其含义适合作为记忆辅助。6. 错误处理优雅地“拒绝”好的错误处理让客户端能“凭状态码就知道发生了什么”而不是靠猜。文档列出了三个高频陷阱陷阱一所有错误都返回 200// ❌ 错误做法 HTTP/1.1 200 OK { error: 出错了 }问题在于缓存层会把这个“成功”响应存下来监控系统也无法发现异常。陷阱二错误信息过于笼统// ❌ 错误做法 HTTP/1.1 400 Bad Request { message: 参数错误 }问题在于客户端不知道是哪个参数错、为什么错。陷阱三泄露敏感信息// ❌ 危险做法 HTTP/1.1 500 Internal Server Error { stack: at UserService.login..., sql: SELECT * FROM... }风险暴露了代码结构与数据库查询语句可被攻击者利用。仓库中对应的教学组件 ErrorHandlingDemo.vue 提供了“好/坏”错误响应设计的对比交互与上述三个陷阱形成正反对照。7. 版本控制API 的“向前兼容”动机假设你的应用有大量用户需要修改订单接口。若不做版本控制旧应用调用新接口会因字段缺失而崩溃。正确做法是让新旧版本并存/v1/orders—— 旧接口继续服务老应用/v2/orders—— 新接口承载新功能。三种版本控制策略对比策略示例优点缺点URL 路径/v1/users直观、易缓存URL 变长请求头Accept: vnd.api.v2jsonURL 干净不便于手工调试查询参数/users?version2简单标准化程度不足版本演进示例以用户与订单为例原文档位于 api-design.md 第 238 节接口v1旧v2新变更说明获取用户GET /v1/users返回name, emailGET /v2/users返回name, email, avatar, phone新增头像与手机号字段创建订单POST /v1/orders接收items[]POST /v2/orders接收items[], coupons[]新增优惠券支持批量操作无POST /v2/orders/batch新增批量创建接口版本控制最佳实践文档原文四条保持向后兼容v1 接口至少维护 6–12 个月给客户端留出升级时间文档同步更新每个版本维护独立的 API 文档下线预告提前公告 v1 的废弃时间引导用户迁移监控用量统计 v1 的调用量确认可以安全下线后再停服。8. 响应结构设计大厂规范借鉴响应结构是前后端协作的“数据契约”统一格式能显著降低沟通成本。文档先引用了响应结构演示组件ResponseStructureDemo.vue再逐一拆解业界规范Google API 设计规范要求所有 API 错误响应包含统一的error结构{ error: { code: 429, message: 资源不足请稍后重试, status: RESOURCE_EXHAUSTED, details: [ { type: type.googleapis.com/google.rpc.ErrorInfo, reason: RESOURCE_AVAILABILITY, domain: compute.googleapis.com, metadata: { zone: us-east1-a, service: compute } } ] } }要点details中必须包含机器可读的错误标识ErrorInfomessage面向开发者简洁描述问题与解决办法details可携带本地化消息、帮助链接等扩展信息。Microsoft REST API 指南强调错误分类与响应头规范错误Error由客户端发送无效数据引起返回 4xx不影响 API 可用性故障Fault服务端无法正确处理有效请求返回 5xx影响可用性响应头DateRFC 5322 GMT 格式、Content-Type必须返回支持乐观并发控制的资源必须返回ETag。阿里巴巴 Java 开发手册给出了统一返回对象与错误码分段设计public class ResultT { private Integer code; private String message; private T data; private String requestId; }码段类型示例0成功01xxxx参数错误10001 必填参数缺失2xxxx业务错误20001 余额不足3xxxx认证错误30001 未登录5xxxx系统错误50001 数据库异常Stripe API 的错误响应设计得极为精细{ error: { type: card_error, code: card_declined, message: Your card was declined., param: number, decline_code: insufficient_funds, doc_url: https://stripe.com/docs/error-codes/card-declined } }设计亮点type区分错误大类api_error、card_error、invalid_request_errorparam精确指出哪个参数出错前端可直接定位到表单字段doc_url提供文档链接decline_code提供更细粒度的错误原因。JSON:API 规范是业内广泛采用的 JSON 响应标准{ data: { type: articles, id: 1, attributes: { title: JSON:API 规范详解 }, relationships: { author: { data: { type: users, id: 9 } } } }, included: [ { type: users, id: 9, attributes: { name: 张三 } } ] }核心设计data携带主资源必须包含type与idattributes存资源属性relationships描述资源关联included一次性返回关联数据避免重复请求。GitHub REST API则展示了面向开发者体验的设计成功响应中同时提供多种 URL 形态html_url、url便于不同场景使用错误响应附带documentation_url指向文档使用Link响应头实现分页导航。Twitter/X API v2采用简洁的dataincludes结构includes类似 JSON:API 的included支持?tweet.fieldscreated_at,public_metrics形式的字段选择分页使用next_token/previous_token。8.1 响应结构最佳实践汇总综合上述规范文档总结了响应结构设计的五条原则一致性优先所有接口使用同一响应结构前端可统一封装请求层机器可读错误码 原因码reason让程序能自动处理人类友好message清晰并给出解决建议可追踪request_id贯穿整个请求链路方便定位问题支持国际化通过 details 扩展翻译后的消息。data字段的设计规范与错误响应的进阶设计分别由 DataFieldDesignDemo.vue 和 ErrorResponseDesignDemo.vue 两个交互组件展开演示。9. 实战演练电商系统 API 完整设计文档给出的综合示例覆盖了用户、订单、产品三个模块原文见 api-design.md 第 8 节# 用户模块 GET /v1/users # 获取用户列表 POST /v1/users # 创建新用户 GET /v1/users/{id} # 获取用户详情 PUT /v1/users/{id} # 完整更新用户 PATCH /v1/users/{id} # 部分更新用户 DELETE /v1/users/{id} # 删除用户 # 订单模块 GET /v1/users/{id}/orders # 获取某用户的订单 POST /v1/orders # 创建订单 GET /v1/orders/{id} # 获取订单详情 PATCH /v1/orders/{id}/status # 更新订单状态 # 商品模块复杂过滤使用查询参数 GET /v1/products?categoryphoneprice_max5000sortprice_descpage1这段清单恰好是前述全部规则的落地URL 全为复数名词、版本前缀/v1/、方法语义正确完整更新用 PUT、状态变更用 PATCH、嵌套关系用户下的订单不超过 3 层、复杂过滤条件全部收敛到查询参数。10. 用 AI 辅助 API 设计提示词模板与注意事项easy-vibe 作为一门 AI 编程课程专门给出了“让 AI 按规范产出 API 设计”的完整工作流。10.1 提示词模板你是一名后端架构师精通 RESTful API 设计。请帮我设计一组 API 接口。 ## 业务背景 [描述你的业务场景比如电商系统、博客平台、任务管理等] ## 功能需求 [列出需要的功能模块比如 - 用户管理注册、登录、个人信息 - 订单管理创建订单、查询订单、取消订单 - 商品管理商品列表、商品详情、搜索] ## 设计要求 1. 遵循 RESTful 规范 2. URL 使用复数名词、小写 连字符 3. 正确使用 HTTP 方法GET/POST/PUT/PATCH/DELETE 4. 统一响应格式{ code, message, data, request_id } 5. 合理使用状态码 6. 版本控制URL 路径方式/v1/ ## 输出格式 请按以下格式输出 ### 接口清单 | 方法 | URL | 描述 | 请求体 | 响应体 | |------|-----|------|--------|--------| ### 请求/响应示例 [主要接口的详细示例] ### 状态码说明 [使用的状态码及其含义]模板的关键在于“明确的上下文 明确的约束条件”把命名规则、响应格式、版本策略全部写进提示词AI 的输出才稳定可控。10.2 应用示例电商订单 API输入提示词你是一名后端架构师精通 RESTful API 设计。请帮我设计一组电商订单系统的 API 接口。 ## 业务背景 一个 B2C 电商平台用户可以浏览商品、提交订单、查看订单状态。 ## 功能需求 - 订单模块创建订单、查询订单列表、查询订单详情、取消订单、支付订单 - 购物车模块添加商品、修改数量、删除商品、查看购物车 ## 设计要求 1. 遵循 RESTful 规范 2. URL 使用复数名词、小写 连字符 3. 正确使用 HTTP 方法 4. 统一响应格式 5. 版本控制/v1/AI 示例输出文档原文的接口清单方法URL描述POST/v1/orders创建订单GET/v1/orders查询订单列表GET/v1/orders/{id}查询订单详情PATCH/v1/orders/{id}/status更新订单状态取消/支付GET/v1/users/{id}/cart获取购物车POST/v1/users/{id}/cart/items添加商品到购物车PATCH/v1/users/{id}/cart/items/{itemId}修改购物车商品数量DELETE/v1/users/{id}/cart/items/{itemId}删除购物车商品10.3 AI 辅助设计的注意事项注意点说明提供完整上下文业务背景、用户角色、数据关系都要说清楚明确约束条件命名规则、版本策略、响应格式要提前定义迭代优化第一次输出未必完美追问细节、要求修改人工审核AI 生成内容需人工审查确保符合业务需求补充边界情况让 AI 考虑错误处理、权限控制、分页等边界情况文档还推荐了几条常用的追问话术“请为每个接口补充错误响应示例”“请考虑分页、排序和筛选参数”“请为接口补充权限控制说明”“请检查是否符合 RESTful 最佳实践”。11. 术语速查表文档最后附上术语速查表便于回顾术语英文解释APIApplication Programming Interface程序间的对话协议RESTRepresentational State Transfer架构风格用 URL 标识资源资源ResourceREST 架构中的基本对象有唯一标识URL幂等性Idempotency多次执行操作得到相同结果状态码Status CodeHTTP 协议定义响应状态的码版本控制Versioning让 API 新旧版本共存便于平滑升级请求体Request BodyPOST/PUT/PATCH 请求发送的数据响应体Response Body服务器返回的数据头部Header请求/响应的元数据如 Content-Type认证Authentication验证“你是谁”登录、Token授权Authorization验证“你能做什么”权限12. 延伸在 easy-vibe 仓库中继续学习本章的前置阅读是 API 入门篇 api-intro.md其配套演示组件ApiPlayground、HttpMethodsDemo、StatusCodeCategories 等位于 docs/.vitepress/theme/components/appendix/api-intro/ 目录同目录下的 auth-authorization.md 讲解认证与授权可与本文的术语表中“认证/授权”条目衔接阅读附录全部 9 章的导航入口在 docs/ar-sa/appendix/index.md中文版在 docs/zh-cn/appendix/index.md本仓库基于 VitePress 构建见 package.json 中vitepress依赖与dev脚本各语言版本文档zh-cn、en、ja-jp、ko-kr、de-de、fr-fr、es-es、vi-vn、zh-tw、ar-sa共享同一套 主题组件 与布局因此文中提到的交互演示组件在所有语言版本中行为一致。【免费下载链接】easy-vibe vibe coding 101The first course for AI-native product builders.项目地址: https://gitcode.com/GitHub_Trending/ea/easy-vibe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考