尧图网站建设 
简介这份《API接口设计规范》文档面向后端开发、接口联调与测试人员以及需要统一团队接口约定的技术负责人用于解决接口风格混乱、参数命名随意、错误码不统一等协作痛点。资源包共1个docx文件约20KB内容以规范条文与示例代码为主便于直接查阅和落地。文档系统梳理了RESTful设计原则、JSON数据格式约定、路径版本与业务分层规则并给出limit、offset、page、per_page、sort_by、order等请求参数的标准用法以及200至500响应码、Result统一返回对象、ResultCode枚举等响应与错误处理方案。安全性方面涵盖token身份验证、权限控制、HTTPS加密与参数签名防篡改还强调requestId追踪和隐私字段脱敏。目前已有3578人学习适合作为团队接口评审与开发自查的参考依据。1. 接口设计规范不是文档摆设从三个线上事故说起很多团队都有一份API接口设计规范.docx但真正把它当回事的没几个。我见过最典型的场景是后端同学花两天写完接口前端联调时发现分页参数一会儿是page一会儿是offset错误码有的返回 HTTP 500 有的返回 200 带{code: -1}字段命名一会儿驼峰一会儿下划线。联调群里吵了三天最后靠前端写适配层硬扛过去。这份规范文档如果只是躺在 Confluence 里没人执行那它和不存在没有区别。接口设计规范要解决的核心问题就三个一致性、可预测性、可演进性。一致性让调用方不用猜可预测性让错误处理有章可循可演进性让接口在业务变化时不至于推倒重来。适合谁看正在从零搭建后端服务的团队、接口被多个客户端消费的中间层开发者、以及接手了一堆历史接口需要做治理的维护者。下面我按实际落地顺序把这份规范拆成能直接抄的条款和代码。2. URL 与资源命名把 RESTful 落到目录结构上2.1 资源导向的路径设计原则接口路径的第一原则是用名词表示资源用 HTTP 方法表示动作。常见做法是/api/v1/orders而不是/api/v1/getOrderList。版本号放在路径里是最简单可靠的方案虽然有人推崇 Header 版本控制但在国内多端协作场景下路径版本号对前端和测试都更友好。资源层级不要超过三层。/users/{userId}/orders/{orderId}/items已经到极限了再深就应该把子资源提出来独立暴露。复数形式统一用复数不要/user和/orders混着来。路径中的单词用连字符-分隔不要用下划线因为下划线在部分终端和日志系统里会被截断或转义。# 推荐的路径风格 GET /api/v1/users # 获取用户列表 GET /api/v1/users/{userId} # 获取单个用户 POST /api/v1/users # 创建用户 PUT /api/v1/users/{userId} # 全量更新 PATCH /api/v1/users/{userId} # 部分更新 DELETE /api/v1/users/{userId} # 删除 # 不推荐 GET /api/getUserById?id123 POST /api/user/create GET /api/user_list上面这段对比的关键在于推荐写法里路径本身就能表达“操作什么资源”方法表达“怎么操作”。参数说明上{userId}这种路径参数适合必填的标识符查询参数?statusactivepage1适合过滤和分页。注意 PUT 和 PATCH 的区别PUT 要求客户端提交完整资源表示PATCH 只提交要改的字段。很多团队只用 PUT 做部分更新这会导致并发场景下未提交的字段被意外覆盖。2.2 查询参数与分页的标准化写法分页是接口设计里最容易各自为政的地方。我一般会强制统一成pagepageSize或者offsetlimit二选一不要两套并存。page从 1 开始还是从 0 开始也要写死我倾向从 1 开始因为前端分页组件默认就是从 1 开始的少一层转换就少一个 bug。排序参数用sortcreatedAt:desc,name:asc这种格式比orderBycreatedAtorderdesc更紧凑。过滤参数直接平铺比如?statusactivetypepremium不要嵌套成?filter[status]active后者在 URL 编码和日志排查时都很烦人。# 分页参数解析的参考实现 from dataclasses import dataclass dataclass class PaginationParams: page: int 1 page_size: int 20 max_page_size: int 100 def __post_init__(self): # 边界保护防止恶意大分页拖垮数据库 if self.page 1: self.page 1 if self.page_size 1: self.page_size 20 if self.page_size self.max_page_size: self.page_size self.max_page_size property def offset(self) - int: return (self.page - 1) * self.page_size # 使用示例 params PaginationParams(page2, page_size50) print(params.offset) # 输出 50这段代码的逻辑说明__post_init__里做了三层保护页码小于 1 强制为 1每页条数超过上限强制截断。参数说明上max_page_size设成 100 是经验值超过这个数数据库的LIMIT扫描成本会明显上升。如果业务确实需要导出大量数据应该走异步导出接口而不是放开分页上限。失败时看什么如果前端反馈“翻到第 3 页数据重复”大概率是排序字段不唯一导致的需要在ORDER BY里追加主键作为兜底排序。3. 请求与响应体字段命名、错误码和版本兼容3.1 字段命名与数据类型约定字段命名统一用snake_case还是camelCase这个没有绝对对错但必须全项目统一。国内团队用snake_case的居多因为和数据库列名一致省一层映射。如果前端是 TypeScriptcamelCase更符合语言习惯。我的建议是后端内部用snake_case网关层做一次转换这样数据库、缓存、日志里的字段名是一致的排查问题时不用在脑子里做映射。时间字段统一用 ISO 8601 格式带时区比如2025-01-15T08:30:0008:00不要用时间戳数字也不要省略时区。布尔字段用is_或has_前缀不要用status: 0/1这种。金额字段用整数分存储返回时可以用字符串避免浮点精度问题。{ user_id: 10086, user_name: zhangsan, is_active: true, created_at: 2025-01-15T08:30:0008:00, balance: 1999, balance_currency: CNY }上面这个响应体的设计要点user_id用数字balance用字符串。为什么金额不用数字因为 JavaScript 的Number类型在超过 2^53 后会丢精度虽然 1999 分没这个问题但规范要按最坏情况定。balance_currency单独一个字段而不是把CNY拼在balance里是为了后续多币种扩展时不用改字段类型。3.2 错误码分层与 HTTP 状态码的配合错误处理是最能体现规范执行程度的地方。我见过最离谱的是所有错误都返回 HTTP 200然后在 body 里放{success: false, error: ...}。这种做法让监控系统完全失效因为从 HTTP 层面看全是成功请求。正确的做法是HTTP 状态码表达传输层和语义层结果业务错误码表达具体原因。400 系列表示客户端问题500 系列表示服务端问题。业务错误码用数字或字符串枚举在文档里列清楚。# 统一错误响应结构 from enum import IntEnum class ErrorCode(IntEnum): INVALID_PARAM 10001 UNAUTHORIZED 10002 RESOURCE_NOT_FOUND 10003 RATE_LIMITED 10004 INTERNAL_ERROR 20001 ERROR_MESSAGES { ErrorCode.INVALID_PARAM: 请求参数不合法, ErrorCode.UNAUTHORIZED: 身份认证失败, ErrorCode.RESOURCE_NOT_FOUND: 请求的资源不存在, ErrorCode.RATE_LIMITED: 请求过于频繁请稍后重试, ErrorCode.INTERNAL_ERROR: 服务内部错误, } def build_error_response(code: ErrorCode, detail: str None): return { error: { code: int(code), message: ERROR_MESSAGES[code], detail: detail, # 仅用于调试生产环境可置空 } }逻辑说明ErrorCode用IntEnum保证错误码是整数且可枚举ERROR_MESSAGES做一层默认文案映射detail字段留给具体上下文。参数说明上错误码分段10000 段给客户端错误20000 段给服务端错误这样看错误码前两位就能判断责任方。注意detail字段在生产环境不要暴露堆栈信息否则就是给攻击者送情报。失败时看什么如果监控发现大量 10004说明限流阈值需要调整或者有客户端在重试风暴要去查调用方的重试策略。4. 避坑与排查接口规范落地时最容易翻车的五个地方4.1 分页参数不统一导致前端写三套适配现象前端在调用不同模块的列表接口时需要写三套分页逻辑因为有的接口用page有的用offset有的用start。原因规范文档只写了“支持分页”没有强制规定参数名和默认值各开发者按自己习惯来。解决在规范里写死分页参数名和默认值并在网关层做参数归一化把offset和start统一转换成page。4.2 错误码在 HTTP 200 里返回导致监控盲区现象线上接口成功率 100%但用户投诉不断因为业务错误全藏在 200 响应里。原因开发者图省事所有响应都返回 200用 body 里的code区分成败。解决强制要求 4xx 和 5xx 必须用对应 HTTP 状态码网关层配置监控规则对 200 响应里error字段非空的请求单独打点。4.3 字段命名混用导致序列化配置冲突现象同一个接口有的字段返回userName有的返回user_name前端解析时好时坏。原因不同开发者用了不同的序列化配置或者引入了多个 JSON 库。解决在项目入口统一配置序列化策略Python 用 Pydantic 的alias_generatorJava 用 Jackson 的PropertyNamingStrategy并在 CI 里加检查。4.4 版本号放在 Header 里导致调试困难现象用 curl 调试接口时总是返回旧版本数据因为忘了加版本 Header。原因版本控制放在Accept或自定义 Header 里浏览器直接访问和 Postman 调试时容易遗漏。解决版本号放路径里/api/v1/这种形式虽然不够“纯正”但调试成本最低。如果必须放 Header在文档里用醒目方式标注。4.5 删除接口用 GET 方法导致被预取现象用户反馈“我没点删除数据就没了”排查发现是浏览器预取了 GET 链接。原因删除操作写成了GET /api/delete?id123浏览器和爬虫会预取 GET 链接。解决删除必须用 DELETE 方法且路径里带资源 IDDELETE /api/v1/users/{userId}。所有产生副作用的操作都不允许用 GET。5. 用 OpenAPI 把规范变成可执行的契约规范写在文档里靠人自觉执行迟早会走样。我的做法是用 OpenAPI 规范文件作为唯一事实来源代码从规范生成文档从规范渲染测试从规范派生。这样规范就不是“建议”而是“契约”。# openapi.yaml 片段 openapi: 3.0.3 info: title: User Service API version: 1.0.0 paths: /api/v1/users: get: summary: 获取用户列表 parameters: - name: page in: query schema: type: integer default: 1 minimum: 1 - name: page_size in: query schema: type: integer default: 20 maximum: 100 responses: 200: description: 成功 content: application/json: schema: $ref: #/components/schemas/UserListResponse 400: description: 参数错误 content: application/json: schema: $ref: #/components/schemas/ErrorResponse这份 YAML 的关键在于page和page_size的默认值、最小值、最大值都写死在规范里代码生成工具会把这些约束带到客户端和服务端。ErrorResponse用$ref复用保证所有接口的错误结构一致。参数说明上maximum: 100和前面 Python 代码里的max_page_size是对应的改的时候要两边同步。验证方法在 CI 里加一步openapi-generator validate规范文件不合法直接阻断合并。再用prism或swagger-ui起一个 mock server前端可以在后端没写完时就开始联调。我一般还会加一个契约测试用 Dredd 或 Schemathesis 跑一遍规范里的所有接口确保实现和规范没有漂移。最后说个血泪经验规范文档不要一次性写五十页然后指望大家看完。我现在的做法是每次代码评审时把规范里对应的条款贴到评论里改一次代码就强化一次记忆。三个月后团队里没人再问“分页参数用哪个”这种问题了。希望帮到你。本文还有配套的精品资源点击获取 API接口设计规范实战：从URL命名到错误码的落地指南
简介这份《API接口设计规范》文档面向后端开发、接口联调与测试人员以及需要统一团队接口约定的技术负责人用于解决接口风格混乱、参数命名随意、错误码不统一等协作痛点。资源包共1个docx文件约20KB内容以规范条文与示例代码为主便于直接查阅和落地。文档系统梳理了RESTful设计原则、JSON数据格式约定、路径版本与业务分层规则并给出limit、offset、page、per_page、sort_by、order等请求参数的标准用法以及200至500响应码、Result统一返回对象、ResultCode枚举等响应与错误处理方案。安全性方面涵盖token身份验证、权限控制、HTTPS加密与参数签名防篡改还强调requestId追踪和隐私字段脱敏。目前已有3578人学习适合作为团队接口评审与开发自查的参考依据。1. 接口设计规范不是文档摆设从三个线上事故说起很多团队都有一份API接口设计规范.docx但真正把它当回事的没几个。我见过最典型的场景是后端同学花两天写完接口前端联调时发现分页参数一会儿是page一会儿是offset错误码有的返回 HTTP 500 有的返回 200 带{code: -1}字段命名一会儿驼峰一会儿下划线。联调群里吵了三天最后靠前端写适配层硬扛过去。这份规范文档如果只是躺在 Confluence 里没人执行那它和不存在没有区别。接口设计规范要解决的核心问题就三个一致性、可预测性、可演进性。一致性让调用方不用猜可预测性让错误处理有章可循可演进性让接口在业务变化时不至于推倒重来。适合谁看正在从零搭建后端服务的团队、接口被多个客户端消费的中间层开发者、以及接手了一堆历史接口需要做治理的维护者。下面我按实际落地顺序把这份规范拆成能直接抄的条款和代码。2. URL 与资源命名把 RESTful 落到目录结构上2.1 资源导向的路径设计原则接口路径的第一原则是用名词表示资源用 HTTP 方法表示动作。常见做法是/api/v1/orders而不是/api/v1/getOrderList。版本号放在路径里是最简单可靠的方案虽然有人推崇 Header 版本控制但在国内多端协作场景下路径版本号对前端和测试都更友好。资源层级不要超过三层。/users/{userId}/orders/{orderId}/items已经到极限了再深就应该把子资源提出来独立暴露。复数形式统一用复数不要/user和/orders混着来。路径中的单词用连字符-分隔不要用下划线因为下划线在部分终端和日志系统里会被截断或转义。# 推荐的路径风格 GET /api/v1/users # 获取用户列表 GET /api/v1/users/{userId} # 获取单个用户 POST /api/v1/users # 创建用户 PUT /api/v1/users/{userId} # 全量更新 PATCH /api/v1/users/{userId} # 部分更新 DELETE /api/v1/users/{userId} # 删除 # 不推荐 GET /api/getUserById?id123 POST /api/user/create GET /api/user_list上面这段对比的关键在于推荐写法里路径本身就能表达“操作什么资源”方法表达“怎么操作”。参数说明上{userId}这种路径参数适合必填的标识符查询参数?statusactivepage1适合过滤和分页。注意 PUT 和 PATCH 的区别PUT 要求客户端提交完整资源表示PATCH 只提交要改的字段。很多团队只用 PUT 做部分更新这会导致并发场景下未提交的字段被意外覆盖。2.2 查询参数与分页的标准化写法分页是接口设计里最容易各自为政的地方。我一般会强制统一成pagepageSize或者offsetlimit二选一不要两套并存。page从 1 开始还是从 0 开始也要写死我倾向从 1 开始因为前端分页组件默认就是从 1 开始的少一层转换就少一个 bug。排序参数用sortcreatedAt:desc,name:asc这种格式比orderBycreatedAtorderdesc更紧凑。过滤参数直接平铺比如?statusactivetypepremium不要嵌套成?filter[status]active后者在 URL 编码和日志排查时都很烦人。# 分页参数解析的参考实现 from dataclasses import dataclass dataclass class PaginationParams: page: int 1 page_size: int 20 max_page_size: int 100 def __post_init__(self): # 边界保护防止恶意大分页拖垮数据库 if self.page 1: self.page 1 if self.page_size 1: self.page_size 20 if self.page_size self.max_page_size: self.page_size self.max_page_size property def offset(self) - int: return (self.page - 1) * self.page_size # 使用示例 params PaginationParams(page2, page_size50) print(params.offset) # 输出 50这段代码的逻辑说明__post_init__里做了三层保护页码小于 1 强制为 1每页条数超过上限强制截断。参数说明上max_page_size设成 100 是经验值超过这个数数据库的LIMIT扫描成本会明显上升。如果业务确实需要导出大量数据应该走异步导出接口而不是放开分页上限。失败时看什么如果前端反馈“翻到第 3 页数据重复”大概率是排序字段不唯一导致的需要在ORDER BY里追加主键作为兜底排序。3. 请求与响应体字段命名、错误码和版本兼容3.1 字段命名与数据类型约定字段命名统一用snake_case还是camelCase这个没有绝对对错但必须全项目统一。国内团队用snake_case的居多因为和数据库列名一致省一层映射。如果前端是 TypeScriptcamelCase更符合语言习惯。我的建议是后端内部用snake_case网关层做一次转换这样数据库、缓存、日志里的字段名是一致的排查问题时不用在脑子里做映射。时间字段统一用 ISO 8601 格式带时区比如2025-01-15T08:30:0008:00不要用时间戳数字也不要省略时区。布尔字段用is_或has_前缀不要用status: 0/1这种。金额字段用整数分存储返回时可以用字符串避免浮点精度问题。{ user_id: 10086, user_name: zhangsan, is_active: true, created_at: 2025-01-15T08:30:0008:00, balance: 1999, balance_currency: CNY }上面这个响应体的设计要点user_id用数字balance用字符串。为什么金额不用数字因为 JavaScript 的Number类型在超过 2^53 后会丢精度虽然 1999 分没这个问题但规范要按最坏情况定。balance_currency单独一个字段而不是把CNY拼在balance里是为了后续多币种扩展时不用改字段类型。3.2 错误码分层与 HTTP 状态码的配合错误处理是最能体现规范执行程度的地方。我见过最离谱的是所有错误都返回 HTTP 200然后在 body 里放{success: false, error: ...}。这种做法让监控系统完全失效因为从 HTTP 层面看全是成功请求。正确的做法是HTTP 状态码表达传输层和语义层结果业务错误码表达具体原因。400 系列表示客户端问题500 系列表示服务端问题。业务错误码用数字或字符串枚举在文档里列清楚。# 统一错误响应结构 from enum import IntEnum class ErrorCode(IntEnum): INVALID_PARAM 10001 UNAUTHORIZED 10002 RESOURCE_NOT_FOUND 10003 RATE_LIMITED 10004 INTERNAL_ERROR 20001 ERROR_MESSAGES { ErrorCode.INVALID_PARAM: 请求参数不合法, ErrorCode.UNAUTHORIZED: 身份认证失败, ErrorCode.RESOURCE_NOT_FOUND: 请求的资源不存在, ErrorCode.RATE_LIMITED: 请求过于频繁请稍后重试, ErrorCode.INTERNAL_ERROR: 服务内部错误, } def build_error_response(code: ErrorCode, detail: str None): return { error: { code: int(code), message: ERROR_MESSAGES[code], detail: detail, # 仅用于调试生产环境可置空 } }逻辑说明ErrorCode用IntEnum保证错误码是整数且可枚举ERROR_MESSAGES做一层默认文案映射detail字段留给具体上下文。参数说明上错误码分段10000 段给客户端错误20000 段给服务端错误这样看错误码前两位就能判断责任方。注意detail字段在生产环境不要暴露堆栈信息否则就是给攻击者送情报。失败时看什么如果监控发现大量 10004说明限流阈值需要调整或者有客户端在重试风暴要去查调用方的重试策略。4. 避坑与排查接口规范落地时最容易翻车的五个地方4.1 分页参数不统一导致前端写三套适配现象前端在调用不同模块的列表接口时需要写三套分页逻辑因为有的接口用page有的用offset有的用start。原因规范文档只写了“支持分页”没有强制规定参数名和默认值各开发者按自己习惯来。解决在规范里写死分页参数名和默认值并在网关层做参数归一化把offset和start统一转换成page。4.2 错误码在 HTTP 200 里返回导致监控盲区现象线上接口成功率 100%但用户投诉不断因为业务错误全藏在 200 响应里。原因开发者图省事所有响应都返回 200用 body 里的code区分成败。解决强制要求 4xx 和 5xx 必须用对应 HTTP 状态码网关层配置监控规则对 200 响应里error字段非空的请求单独打点。4.3 字段命名混用导致序列化配置冲突现象同一个接口有的字段返回userName有的返回user_name前端解析时好时坏。原因不同开发者用了不同的序列化配置或者引入了多个 JSON 库。解决在项目入口统一配置序列化策略Python 用 Pydantic 的alias_generatorJava 用 Jackson 的PropertyNamingStrategy并在 CI 里加检查。4.4 版本号放在 Header 里导致调试困难现象用 curl 调试接口时总是返回旧版本数据因为忘了加版本 Header。原因版本控制放在Accept或自定义 Header 里浏览器直接访问和 Postman 调试时容易遗漏。解决版本号放路径里/api/v1/这种形式虽然不够“纯正”但调试成本最低。如果必须放 Header在文档里用醒目方式标注。4.5 删除接口用 GET 方法导致被预取现象用户反馈“我没点删除数据就没了”排查发现是浏览器预取了 GET 链接。原因删除操作写成了GET /api/delete?id123浏览器和爬虫会预取 GET 链接。解决删除必须用 DELETE 方法且路径里带资源 IDDELETE /api/v1/users/{userId}。所有产生副作用的操作都不允许用 GET。5. 用 OpenAPI 把规范变成可执行的契约规范写在文档里靠人自觉执行迟早会走样。我的做法是用 OpenAPI 规范文件作为唯一事实来源代码从规范生成文档从规范渲染测试从规范派生。这样规范就不是“建议”而是“契约”。# openapi.yaml 片段 openapi: 3.0.3 info: title: User Service API version: 1.0.0 paths: /api/v1/users: get: summary: 获取用户列表 parameters: - name: page in: query schema: type: integer default: 1 minimum: 1 - name: page_size in: query schema: type: integer default: 20 maximum: 100 responses: 200: description: 成功 content: application/json: schema: $ref: #/components/schemas/UserListResponse 400: description: 参数错误 content: application/json: schema: $ref: #/components/schemas/ErrorResponse这份 YAML 的关键在于page和page_size的默认值、最小值、最大值都写死在规范里代码生成工具会把这些约束带到客户端和服务端。ErrorResponse用$ref复用保证所有接口的错误结构一致。参数说明上maximum: 100和前面 Python 代码里的max_page_size是对应的改的时候要两边同步。验证方法在 CI 里加一步openapi-generator validate规范文件不合法直接阻断合并。再用prism或swagger-ui起一个 mock server前端可以在后端没写完时就开始联调。我一般还会加一个契约测试用 Dredd 或 Schemathesis 跑一遍规范里的所有接口确保实现和规范没有漂移。最后说个血泪经验规范文档不要一次性写五十页然后指望大家看完。我现在的做法是每次代码评审时把规范里对应的条款贴到评论里改一次代码就强化一次记忆。三个月后团队里没人再问“分页参数用哪个”这种问题了。希望帮到你。本文还有配套的精品资源点击获取