社交平台后端微服务接口定义规范

社交平台后端微服务接口定义规范一、接口设计原则（一）标准化统一。接口命名需遵循小写字母、下划线分隔的规范，统一采用RESTful风格，各服务接口版本号需标注在URL路径中，遵循语义化版本控制规则，主版本号每重大迭代更新，次版本号每新增功能更新，修订号每修复bug更新，错误示范为直接在请求头中传递版本信息。1.接口命名规范接口名称需使用动词开头，明确操作类型，如getUserProfile表示获取用户资料操作，createPost表示创建动态操作，命名需保持一致性，避免出现getUserInfo和getUserProfile两种命名方式并存的情况。2.请求方法规范GET方法仅用于数据查询，禁止在请求体中传递参数，参数需通过URL查询字符串传递，POST方法仅用于数据创建，PUT方法仅用于数据更新，DELETE方法仅用于数据删除，禁止出现同时使用POST和PUT更新数据的情况。3.响应状态码规范成功响应统一使用200OK，创建成功使用201Created，客户端错误使用4xx，服务器错误使用5xx，各状态码需对应明确语义，如400表示参数校验失败，401表示认证失败，500表示服务器内部错误。二、数据传输格式（二）协议适配。所有接口默认使用HTTPS协议传输，传输内容必须使用JSON格式，禁止使用XML或其他格式，JSON对象属性名需全部小写，数组元素必须保持一致的属性结构，错误示范为在JSON中混用大写属性名。1.JSON数据规范请求参数和响应数据必须使用JSON格式，对象属性名不能包含特殊字符，必须使用标准ASCII字符，数组元素不能包含null值，必须使用有效数据替代，响应头Content-Type必须设置为application/json。2.字符编码规范所有接口传输必须使用UTF-8编码，禁止使用ISO-8859-1或其他编码，响应头Content-Type中必须包含charset=utf-8参数，客户端发送请求时必须设置Accept:application/json，服务器响应时必须设置Content-Type:application/json;charset=utf-8。3.数据加密规范敏感数据如密码、手机号等必须使用AES-256加密，加密密钥需通过安全方式传输，不能明文传输，接口响应中必须使用CORS头部允许跨域访问，Access-Control-Allow-Origin需设置为*或具体域名。三、认证授权机制（三）安全防护。所有接口必须进行身份认证，认证方式统一使用JWT令牌，令牌有效期最长不超过24小时，必须使用HS256算法签名，令牌需存储在HTTPOnly的Cookie中，禁止在请求头中传递。1.JWT令牌规范令牌格式为Bearer{token}，客户端必须在每个请求的Authorization头中传递，服务器需验证令牌有效性，包括签名校验、过期校验和权限校验，令牌失效时需返回401状态码。2.权限控制规范必须实现基于角色的访问控制，管理员拥有最高权限，普通用户只能访问自己的数据，接口需根据用户角色和请求类型进行权限校验，禁止越权访问，权限校验失败返回403状态码。3.认证流程规范用户登录成功后必须返回JWT令牌，客户端需存储令牌并在后续请求中使用，令牌刷新需通过POST/api/refreshToken接口实现，刷新请求必须携带原令牌，服务器验证通过后返回新令牌。四、接口版本管理（四）演进控制。所有接口必须支持版本管理，版本号统一放在URL路径中，如/api/v1/users，主版本号从1开始，次版本号每重大变更增加，修订号每修复bug增加，禁止直接在请求体中传递版本信息。1.版本发布规范新版本接口发布前必须进行充分测试，旧版本接口至少保留3个月，版本升级需通过灰度发布完成，禁止直接将旧版本接口下线，版本变更需在API文档中明确标注。2.兼容性维护新版本接口必须保持对旧版本接口的兼容性，数据结构变更需使用向后兼容的方式，如新增字段默认为空，删除字段需提供迁移工具，接口变更需提前30天发布通知。3.版本废弃流程废弃接口需提前60天发布通知，通知中明确废弃时间、替代方案和迁移指南，废弃接口需保留3个月，期间禁止调用，3个月后直接下线，并在API文档中标记为已废弃。五、错误处理规范（五）异常处理。所有接口必须定义统一的错误响应格式，错误码必须使用4位数字，前两位表示错误类型，后两位表示具体错误，错误信息必须使用中文描述，禁止使用英文或代码片段。1.错误响应格式错误响应必须包含code、message、timestamp、traceId四个字段，code为错误码，message为错误信息，timestamp为错误发生时间，traceId为请求追踪ID，格式为错误码：{code}，错误信息：{message}。2.错误分类规范错误码1000-1999为客户端错误，2000-2999为服务器错误，3000-3999为认证错误，4000-4999为业务逻辑错误，错误码必须保持全局唯一，错误信息必须清晰易懂，避免使用技术术语。3.异常捕获规范所有接口必须捕获所有可能的异常，包括系统异常和业务异常，异常处理需记录完整日志，包括请求参数、响应内容、异常堆栈，异常响应必须使用统一格式，禁止直接返回原始异常信息。六、性能优化要求（六）效率保障。所有接口必须满足200ms内响应要求，接口响应大小必须控制在1MB以内，必须实现缓存机制，热点数据必须预加载，禁止在接口中直接调用其他微服务。1.响应时间规范所有接口必须进行性能测试，平均响应时间不得高于200ms，95%响应时间不得高于500ms，接口响应慢时需进行性能优化，包括数据库查询优化、缓存使用、异步处理等。2.资源占用规范接口响应大小必须控制在1MB以内，超过1MB的响应必须进行分页处理，图片等大文件需使用流式传输，禁止直接返回完整文件内容，接口处理内存占用不得高于500MB。3.缓存策略规范热点数据必须使用Redis缓存，缓存有效期根据数据更新频率设置，缓存穿透需使用布隆过滤器，缓存击穿需使用互斥锁，缓存雪崩需使用分布式锁，缓存数据必须定期刷新。七、文档维护规范（七）文档管理。所有接口必须提供完整文档，文档必须包含接口描述、请求参数、响应数据、错误码、示例代码，文档更新必须同步代码变更，文档必须定期审核保证准确性。1.文档内容规范每个接口必须提供详细描述，包括接口功能、适用场景、请求参数、响应数据、错误码、示例代码，文档必须使用统一格式，接口描述必须清晰简洁，避免使用模糊表述。2.文档更新规范文档更