Go语言后端代码编写规范

Go语言后端代码编写规范一、命名规范（一）文件命名。项目模块名称应使用小写字母，多个单词之间用下划线分隔，例如user_profile.go。接口文件命名需体现功能，如get_user_info.go。（二）变量命名。局部变量使用小写字母，如count。全局变量首字母大写，如MaxLimit。常量全大写，如MAX_TIMEOUT。（三）函数命名。动词开头，如calculateScore（）。避免使用缩写，如processData（）而非procData（）。（四）类型命名。使用大写首字母，如UserInfo。自定义类型需体现其含义，如BalanceCalculator。（五）包命名。使用单一单词，如utils。避免使用中文或特殊字符。二、代码结构规范（一）包划分。每个包应聚焦单一职责，如api包处理HTTP请求，model包管理数据结构。包名需与目录结构一致。（二）文件组织。每个功能模块独立成文件，避免单个文件超过1000行。文件命名需体现其功能模块。（三）代码分层。采用分层架构，自顶向下依次为：路由层、业务逻辑层、数据访问层、实体层。每层职责明确。（四）目录规范。根目录下必须包含main.go和config文件夹。模块目录命名需使用名词，如database、service。（五）代码注释。关键逻辑处必须添加注释，说明设计思路。API接口需标注请求参数和返回值说明。三、代码风格标准（一）缩进规范。使用4个空格缩进，禁止使用tab键。每行代码长度不超过120字符。（二）空行使用。函数内部逻辑块之间用1行空行分隔。不同函数之间用2行空行分隔。（三）导入管理。使用gomod管理依赖，避免重复导入。导入包按字母顺序排列，标准库在前。（四）命名空间。全局变量必须首字母大写，局部变量小写。包内变量使用驼峰命名。（五）代码对齐。运算符左右需对齐，如a+bc。条件语句左右括号单独成行。四、函数设计原则（一）单一职责。每个函数只完成一项任务，如getUser（）独立处理用户获取。复杂逻辑需拆分为多个函数。（二）参数规范。函数参数不超过5个，超过需重构。参数类型需显式声明，避免使用interface{}。（三）返回值设计。错误处理使用error类型，不要用bool表示成功失败。复杂接口使用结构体返回。（四）函数命名。动词开头，如calculateTotalPrice（）。避免使用中文或拼音。（五）递归限制。递归深度不超过3层，超过需改用循环实现。递归函数必须标注basecase。五、错误处理机制（一）错误分类。系统错误使用标准库error，业务错误自定义类型。错误码需全局统一管理。（二）错误处理。所有可能产生错误的操作必须处理，如数据库操作需检查返回值。（三）错误记录。生产环境错误必须记录日志，包含请求ID和详细上下文。客户端错误需友好提示。（四）异常捕获。使用recover处理panic，但需限制捕获范围。关键代码块必须使用defer确保资源释放。（五）错误传播。微服务接口使用标准错误码体系，如400表示客户端错误，500表示服务端错误。六、数据库交互规范（一）连接管理。使用数据库连接池，配置最大连接数和最小空闲连接。连接参数需从配置读取。（二）SQL编写。使用预处理语句防止SQL注入。避免使用动态SQL，特殊情况需做安全过滤。（三）事务管理。长事务必须拆分为短事务，每个事务不超过5秒。明确标注事务边界。（四）查询优化。使用索引覆盖查询，避免SELECT*。复杂查询需编写执行计划分析。（五）数据校验。所有入参必须校验，如日期格式、数字范围。校验失败需返回400错误。七、并发编程规范（一）并发模型。优先使用goroutine+channel，避免直接使用sync包。协程数不超过1000个。（二）锁的使用。使用sync.Mutex控制并发，避免死锁。锁粒度尽量细，如行锁代替表锁。（三）channel规范。channel必须带缓冲，缓冲大小根据业务确定。长协程必须使用select非阻塞读取。（四）协程安全。共享变量必须加锁，或使用sync.Once初始化。避免goroutine泄漏。（五）性能测试。并发场景需使用pprof分析性能瓶颈。协程创建销毁成本需考虑。八、API接口设计（一）接口版本。使用URL路径版本控制，如/v1/users。版本号必须全局统一管理。（二）请求参数。必传参数放在路径中，可选参数放在查询字符串。参数类型需显式声明。（三）响应格式。统一使用JSON格式，错误码使用HTTP标准。响应头必须包含Content-Type。（四）接口文档。每个接口必须编写文档，说明请求方法、参数、返回值。使用Swagger自动生成。（五）限流设计。所有接口必须配置限流，使用令牌桶算法。热点接口需单独限流。九、安全防护要求（一）输入验证。所有用户输入必须校验，包括文件上传。使用正则表达式校验格式。（二）权限控制。使用中间件处理认证，JWT有效期不超过1小时。敏感接口必须二次验证。（三）防攻击设计。开启CORS保护，限制请求频率。使用WAF过滤XSS攻击。（四）加密传输。HTTPS必须使用TLS1.2以上版本。敏感数据必须加密存储。（五）安全审计。所有操作必须记录日志，包括登录和权限变更。定期审计安全漏洞。十、测试规范要求（一）单元测试。每个函数必须编写单元测试，覆盖率不低于80%。使用table-driven测试模式。（二）集成测试。核心模块必须编写集成测试，模拟真实业务场景。测试数据需使用Mock。（三）性能测试。高并发接口必须进行压力测试，确定QPS阈值。使用JMeter模拟请求。（四）测试覆盖率。使用gotest-cover分析测试覆盖率。未覆盖代码必须补充测试用例。（五）测试环境。测试环境与生产环境配置一致，使用Docker容器管理测试环境。十一、部署运维规范（一）部署流程。使用CI/CD自动化部署，配置版本回滚机制。部署前必须自检。（二）日志管理。所有接口必须记录结构化日志，包含请求ID。日志保留时间不少于30天。（三）监控告警。核心指标必须监控，如CPU使用率、接口响应时间。告警阈值需分级管理。（四）资源限制。容器资源限制必须配置，避免资源抢占。内存使用超