RESTful API接口定义标准文档

RESTfulAPI接口定义标准文档一、总则（一）适用范围。本标准适用于公司所有业务系统及第三方系统间交互的RESTfulAPI接口设计与开发，涵盖接口定义、数据格式、协议规范、版本管理等全生命周期管理要求。（二）基本原则。接口设计应遵循标准化、模块化、安全性、可扩展性原则，确保系统间数据交互的准确性与高效性。二、接口设计规范（一）资源命名。接口资源名称必须使用名词或名词短语，采用小写字母，多个单词间使用下划线分隔，如user_info。资源名称需保持全局唯一性，禁止使用特殊字符。（二）HTTP方法。接口方法必须严格遵循HTTP标准方法定义：1.GET：用于查询资源，禁止在请求体中传递数据。2.POST：用于创建资源，请求体必须包含JSON格式数据。3.PUT：用于更新资源，请求体必须包含JSON格式数据。4.DELETE：用于删除资源，无请求体。（三）路径设计。接口路径必须采用层级结构，禁止使用动词开头，如/api/v1/users/{userId}/roles。版本号必须置于路径最前方，使用/v数字格式。三、数据格式规范（一）请求参数。所有请求参数必须通过URL查询字符串或请求体传递，禁止使用HTTP头传递业务参数。（二）数据类型。接口参数必须明确数据类型，包括：1.整型：必须使用int32或int64类型，禁止使用float类型表示整数。2.字符串：必须使用UTF-8编码，禁止使用ISO-8859-1编码。3.日期时间：必须使用ISO8601格式，如2023-06-15T08:30:00Z。（三）请求体格式。所有JSON请求体必须符合以下要求：1.必填字段必须使用required关键字标注。2.对象属性必须使用camelCase命名，如userId。3.数组类型必须使用[]标识，如roles[]。四、响应格式规范（一）状态码。响应状态码必须严格遵循HTTP标准，包括：1.2xx：成功响应，如200OK。2.4xx：客户端错误，如400BadRequest。3.5xx：服务器错误，如500InternalServerError。（二）响应体格式。所有JSON响应体必须包含以下标准字段：1.code：数字类型状态码，如200。2.message：字符串类型提示信息，如"操作成功"。3.data：对象类型返回数据，可为null。（三）分页处理。所有列表接口必须支持分页，请求参数必须包含：1.page：当前页码，默认1。2.limit：每页数量，默认10。五、版本管理规范（一）版本号规则。版本号必须采用主版本.次版本.修订号格式，如1.0.0。主版本升级表示不兼容变更，次版本升级表示向后兼容新增，修订号升级表示向后兼容修复。（二）变更发布。版本变更必须通过API版本控制网关发布，禁止直接暴露旧版本接口。新版本发布必须提前发布变更公告，明确变更内容与兼容性说明。六、安全规范（一）认证机制。所有接口必须实现认证，推荐使用OAuth2.0或JWT标准，禁止使用明文密码传输。（二）权限控制。必须实现基于角色的访问控制，接口必须明确声明requiredRole字段，如{"requiredRole":"admin"}。（三）数据加密。所有敏感数据必须使用HTTPS传输，禁止使用HTTP协议。密码字段必须使用bcrypt算法加密存储。七、错误处理规范（一）错误码定义。必须使用5位数字错误码，前三位表示错误类型，后两位表示具体错误，如10001表示参数校验失败。（二）错误响应。错误响应必须包含以下字段：1.errorCode：错误码。2.errorMessage：错误信息。3.field：错误字段（可选）。4.suggestion：修复建议（可选）。八、测试验收标准（一）功能测试。必须覆盖所有接口的GET/POST/PUT/DELETE方法，包括正常场景与异常场景。（二）性能测试。接口响应时间必须小于200ms，并发请求量必须支持每秒1000次以上。（三）安全测试。必须通过OWASPTop10漏洞扫描，禁止存在SQL注入、XSS攻击等安全风险。九、运维规范（一）监控要求。所有接口必须接入APM系统，监控指标包括：1.响应时间。2.错误率。3.并发量。（二）日志规范。必须实现全量请求日志，日志格式必须包含：1.请求时间。2.请求方法。3.请求路径。4.请求头。5.请求体。6.响应状态码。7.响应时间。十、附则（一）文档更新。本标准文档必须随接口变更同步更新，更新版本号必须与API版本号保持一致。（二）责任主体。接口设计、开发、测试、运维各环节责任人必须签字确认，确保标准执行到位。（三）