前后端API接口定义标准规范

前后端API接口定义标准规范一、总则（一）目的明确。为规范前后端API接口定义，提升系统交互效率，本标准旨在统一接口设计语言，减少开发成本，确保系统稳定性，规范目的明确。1.适用范围本标准适用于公司所有新开发及改扩建项目的前后端API接口定义，包括但不限于Web应用、移动应用、第三方系统集成等场景。所有涉及前后端数据交互的接口设计必须遵循本规范。2.基本原则（1）标准化原则。接口命名、参数定义、数据格式、错误处理等必须遵循统一标准，避免随意性。（2）易用性原则。接口设计应简洁直观，减少调用复杂度，提高开发效率。（3）可扩展性原则。接口设计应预留扩展空间，适应未来业务变化需求。（4）安全性原则。接口必须具备必要的防护措施，防止未授权访问和数据泄露。二、接口命名规范（一）命名规则。接口命名应遵循"资源+动词"结构，清晰表达接口功能。资源名称使用名词或名词短语，动词表示操作类型，如"getUserProfile"表示获取用户信息。1.资源名称规范（1）使用小写字母表示资源，多个单词之间用下划线分隔，如"user_info"。（2）资源名称应具有唯一性，避免歧义，如"order_detail"表示订单详情，而非订单明细。（3）资源名称应与数据库表名保持一致，便于开发人员理解。2.动词操作规范（1）GET：用于查询操作，不改变资源状态，如"get_user_list"。（2）POST：用于创建新资源，如"create_order"。（3）PUT：用于更新现有资源，如"update_user_info"。（4）DELETE：用于删除资源，如"delete_user"。（5）PATCH：用于部分更新资源，如"partial_update_order"。3.特殊场景处理（1）资源名称为多单词时，首字母大写，如"UserProfile"。（2）资源名称为中文时，使用拼音全拼，如"zhongguo_dianzi"。（3）资源名称为缩写时，需有明确说明，如"api_token"。三、参数定义规范（一）参数分类。接口参数分为必选参数、可选参数和请求体参数，需明确区分并标注。1.必选参数规范（1）必选参数必须使用大写字母表示参数名，多个单词之间用下划线分隔，如"USER_ID"。（2）必选参数应在URL中传递，避免在请求体中传递。（3）必选参数值不能为空，调用时必须提供有效值。2.可选参数规范（1）可选参数使用小写字母表示参数名，多个单词之间用下划线分隔，如"page_size"。（2）可选参数应在请求体中传递，避免影响URL可读性。（3）可选参数应有默认值，调用时可省略。3.请求体参数规范（1）复杂参数结构应使用JSON格式传递，如用户信息、订单详情等。（2）请求体参数名使用小写字母，多个单词之间用下划线分隔，如"user_data"。（3）请求体参数应进行嵌套，保持结构清晰，如"address.city"表示城市信息。四、数据格式规范（一）数据类型定义。接口参数及返回值的数据类型必须明确标注，前后端需保持一致。1.基本数据类型（1）字符串：使用"string"表示，如用户名、地址等。（2）整数：使用"integer"表示，如ID、数量等。（3）浮点数：使用"float"表示，如价格、评分等。（4）布尔值：使用"boolean"表示，如状态标识、开关等。（5）日期时间：使用"datetime"表示，格式为"YYYY-MM-DDHH:MM:SS"。2.复合数据类型（1）数组：使用"array"表示，如商品列表、标签集合等。（2）对象：使用"object"表示，如用户信息、地址详情等。（3）枚举：使用"enum"表示，如状态码、性别等。3.数据格式约束（1）字符串参数需标注长度限制，如"username:string（50）"。（2）整数参数需标注范围限制，如"user_id:integer（1,100）"。（3）日期时间参数必须使用标准格式，如"order_date:datetime"。五、错误处理规范（一）错误码定义。接口错误码必须使用4位数字表示，前两位表示错误类型，后两位表示具体错误。1.错误码分类（1）1xx：客户端错误，如参数错误、权限不足等。（2）2xx：服务器错误，如系统异常、数据库故障等。（3）3xx：网络错误，如连接超时、服务不可达等。2.错误信息规范（1）错误信息必须使用中文描述，清晰表达错误原因。（2）错误信息应包含错误码、错误描述、建议解决方案。（3）错误信息应避免使用技术术语，便于非技术人员理解。3.错误响应结构（1）状态码：使用HTTP标准状态码，如400表示客户端错误。（2）响应体：包含错误码、错误信息、建议解决方案，如"{"code":400,"message":"参数错误，请检查参数格式","solution":"请参考API文档"}"。六、版本管理规范（一）版本控制。接口版本必须明确标注，新版本发布需遵循向后兼容原则。1.版本号格式（1）使用"主版本号.次版本号.修订号"格式，如"1.0.0"。（2）主版本号：重大变更时递增，如API结构变更。（3）次版本号：新增功能时递增，如添加新接口。（4）修订号：修复bug时递增，如参数调整。2.版本发布流程（1）新版本开发前需提交版本申请，说明变更内容。（2）版本发布前需进行接口测试，确保功能正常。（3）版本发布后需通知相关团队，更新开发文档。3.兼容性原则（1）新版本应保持对旧版本参数的兼容性。（2）重大变更需提供迁移指南，帮助开发人员适配。（3）废弃接口需提前通知，并提供替代方案。七、安全规范（一）安全要求。接口必须具备必要的安全防护措施，防止未授权访问和数据泄露。1.认证机制（1）所有接口必须进行认证，如JWT、OAuth等。（2）认证信息必须使用HTTPS传输，防止中间人攻击。（3）认证令牌需定期更换，避免长期有效。2.授权控制（1）接口需根据用户角色进行权限控制，如管理员、普通用户等。（2）敏感接口必须进行二次验证，如修改密码、删除数据等。（3）授权信息需与业务逻辑分离，避免越权操作。3.数据加密（1）敏感数据必须进行加密存储，如密码、银行卡号等。（2）敏感数据传输必须使用HTTPS，防止数据被窃取。（3）加密算法必须使用业界标准，如AES、RSA等。八、文档规范（一）文档要求。接口文档必须完整、准确、易于理解。1.文档结构（1）每个接口应有独立文档，包含接口名称、功能描述、请求参数、响应数据、错误码等。（2）文档应使用表格形式展示参数和返回值，清晰直观。（3）文档应包含示例代码，便于开发人员快速上手。2.文档更新（1）文档必须与代码同步更新，避免脱节。（2）文档更新需经过审核，确保内容准确。（3）文档更新需通知相关团队，避免使用过时信息。3.文档工具（1）推荐使用Swagger、Postman等工具生成文档。（2）文档应支持在线预览，便于查阅。（3）文档应支持版本管理，便于追溯变更历史。九、实施要求（一）执行标准。所有项目开发必须严格遵循本规范，确保接口质量。1.开发阶段（1）接口设计前需进行需求分析，明确功能需求。（2）接口设计后需进行评审，确保符合规范。（3）接口开发前需编写单元测试，确保功能正确。2.测试阶段（1）接口测试必须覆盖所有参数组合，包括边界值。（2）接口测试必须验证数据一致性，前后端结果一致。（3）接口测试必须验证安全性，防止未授权访问。3.上线阶段（1）接口上线前需进行压力测试，确保性能达标。（2）接口上线后需进行监控，及时发现异常。（3）接口上线后需进行版本管理，便于维护。十、附则（一）解释权归属。本标准由技术部负责解释，如有疑问可联系技术部接口负责人。1