微服务Go后端接口定义规范

微服务Go后端接口定义规范一、接口命名规范（一）统一性原则。接口命名必须遵循项目统一编码规范，采用小写字母和短横线组合方式，禁止使用大写字母或下划线，命名长度不超过50字符，正确示范为user-profile.get，错误示范为getUserProfile。（二）语义清晰。接口名称需准确反映操作语义，如查询操作统一使用动词+名词结构，修改操作使用动词+目标对象形式，命名规则需保持全文一致，例如获取用户信息统一为user.get，修改用户信息统一为user.update。（三）版本控制。接口命名需预留版本管理空间，在基础名称后通过冒号分隔添加版本号，格式为base-name:v1，v2等，版本号采用数字形式，禁止使用字母，例如user-profile.get:v1。二、请求参数规范（一）参数类型约束。所有接口参数必须严格遵循Go语言类型规范，基本类型使用string、int、float64、bool，复杂类型使用struct或map，禁止使用interface作为参数类型，日期参数统一使用RFC3339格式。（二）必选参数处理。所有必选参数必须通过URL路径参数传递，禁止使用query参数，参数命名需与实体属性保持一致，例如用户ID参数命名为userId，错误示范为idParam。（三）参数校验。所有参数必须实现非空校验，数值型参数需设置范围限制，枚举型参数需提供完整取值列表，校验规则通过中间件统一实现，禁止在业务逻辑中分散校验，校验失败需返回400状态码并附带详细错误信息。三、响应格式标准（一）统一结构。所有接口响应必须包含三个核心字段，data为实际业务数据、code为状态码、message为提示信息，例如{code:200,message:"成功",data:[]},code值需严格遵循企业级错误码规范。（二）状态码分类。2xx为成功响应，4xx为客户端错误，5xx为服务端错误，各状态码需与HTTP标准保持一致，特殊业务场景可扩展5xx范围，但必须提供详细分类说明，例如50001表示数据库错误，50002表示服务超时。（三）数据格式。业务数据必须使用JSON格式，所有字段需设置默认值，日期字段统一使用RFC3339格式，数组类型参数需设置最小值限制，禁止返回null值，空值统一使用空字符串""表示。四、异常处理机制（一）错误分类。系统错误分为4类，参数错误（400）、权限错误（403）、资源不存在（404）、服务异常（500），各错误类型需提供标准错误码和描述信息，例如参数错误统一使用40001，描述为"缺少必填参数userId"。（二）异常捕获。所有接口必须实现全局异常捕获，通过recover机制处理panic情况，捕获后需转换为标准500错误响应，禁止向客户端泄露堆栈信息，敏感信息需通过日志系统记录。（三）重试机制。对网络异常或临时服务不可用情况，客户端可执行最多3次重试，重试间隔必须为指数退避策略，最小间隔为1秒，最大间隔不超过60秒，重试前需验证服务端健康状态。五、安全防护要求（一）认证机制。所有接口必须实现JWT认证，token通过Authorization头传递，格式为Bearer{token}，服务端需验证token有效性，无效时返回403状态码，禁止使用session认证方式。（二）权限控制。接口需明确声明所需权限级别，通过中间件实现权限校验，权限不足返回403，权限级别通过自定义header传递，格式为X-Permission:admin/user，禁止使用角色硬编码方式。（三）防攻击措施。所有接口必须实现防SQL注入、防XSS攻击、防重放攻击，参数传入前需进行严格清洗，请求频率限制为每分钟1000次，超过限制返回429状态码，禁止使用fixed-length参数。六、接口版本管理（一）变更策略。接口变更必须遵循渐进式演进原则，新增接口需添加到新版本，旧版本保持不变，重大变更需提供迁移方案，禁止直接废弃旧接口，版本升级通过/v1/、/v2/等路径区分。（二）兼容性要求。向后兼容的接口变更必须满足两个条件，新增字段设置为可选，旧版本客户端可忽略；返回字段增加不改变原有语义，禁止修改必选字段类型，版本变更需通过API文档系统同步更新。（三）废弃流程。废弃接口需提前30天发布通知，通知内容包括废弃原因、替代方案、最后调用时间，废弃后需保留历史接口至少6个月，废弃接口返回特定状态码426，提示"该接口已废弃"。七、性能优化标准（一）响应时间。所有接口P95响应时间不得超过200ms，慢查询接口需设置单独监控，慢查询定义为执行时间超过500ms的请求，通过中间件记录慢查询并生成告警。（二）资源消耗。接口内存占用不得超过200MB，CPU使用率峰值不得超过30%，资源消耗通过Prometheus监控系统采集，异常情况需触发自动扩容，禁止使用全局变量存储共享数据。（三）缓存策略。热点接口必须实现二级缓存，一级缓存使用Redis，有效期5分钟，二级缓存使用本地内存，有效期2分钟，缓存失效需通过订阅消息队列实现自动更新，禁止使用定时任务轮询。八、文档与测试要求（一）文档标准。接口文档必须包含五个核心要素，请求路径、请求方法、参数列表、响应示例、错误码说明，文档通过Swagger自动生成，更新后需同步到Git仓库，禁止使用静态文档方式。（二）测试覆盖。核心接口测试覆盖率必须达到100%，通过Postman编写自动化测试用例，测试用例需覆盖所有分支场景，测试结果通过Jenkins自动执行，失败用例需触发告警并暂停接口发布。（三）发布流程。接口发布必须遵循三阶段流程，开发环境验证、测试环境验证、生产环境验证，每个阶段需通过QA签字确认，发布前需执行接口压力测试，测试报告作为发布依据，禁止直接在生产环境部署未验证接口。九、运维监控规范（一）监控指标。必须监控六个核心指标，接口成功率、平均响应时间、错误率、并发量、慢查询数、资源消耗，监控数据通过Grafana可视化展示，异常情况需触发短信告警，告警阈值按业务级别设置。（二）日志规范。所有接口请求必须记录结构化日志，日志格式包括请求ID、接口名称、请求时间、响应时间、状态码、参数、错误信息，日志保留周期为90天，通过ELK系统集中管理，禁