编码规范

---

本规范适用于　　仓库全部生产代码；存量代码遵循「谁改动、谁治理」，触碰即顺手对齐。例外须在 MR 中说明并经 　　　　同意。

一、命名规范

场景	规范	正确示例	反例
变量 / 函数	小驼峰，名词或动宾短语	userId / getUserOrders()	uid2 / data1 / do()
类 / 类型	大驼峰，名词	OrderService	orderService / svc
常量	全大写下划线	MAX_RETRY_COUNT	maxRetry
布尔	is / has / can 前缀	isActive / hasPermission	activeFlag
接口路径	小写中划线复数名词	/api/v1/order-items	/api/v1/orderItems
数据库	snake_case，禁保留字	order_item.created_at	orderItem.CreateTime

二、格式与注释

• 统一使用仓库根 .editorconfig 与格式化工具（　　　　），提交前本地格式化，CI 卡格式漂移；
• 单文件不超过 　　 行，函数不超过 　　 行，超限拆分；嵌套不超过 　　 层，优先早返回；
• 注释写「为什么」而非「做了什么」；公共 API 注释遵循语言文档规范（如 JSDoc / godoc）；
• 禁注释掉的死代码入库，历史代码由 Git 追溯；TODO 格式：TODO(工号): 说明 + 截止 2026-　-　。

三、错误与异常处理

// Good：错误逐层包装，带上下文；不吞错
if err := s.repo.CreateOrder(ctx, order); err != nil {
    return fmt.Errorf("create order %s: %w", order.ID, err)
}

// Bad：吞错 + 泛化异常，故障排查无从下手
try { ... } catch (e) { /* 忽略 */ }

• 错误必须处理：要么向上传递、要么记录日志并说明吞掉的理由；
• 对外错误码走统一错误体系（internal/errcode），禁止裸抛内部堆栈给客户端；
• 边界输入（用户输入、外部接口返回）一律校验后使用，杜绝默认信任。

四、安全与性能基线

• SQL 一律参数化查询，禁止字符串拼接 SQL
• 密钥 / 口令不入代码库，走配置中心或环境变量
• 日志不打印敏感字段（手机号 / 身份证 / Token 需脱敏）
• 循环内禁查库 / 调外部接口，改为批量接口
• 新增依赖须经评审，说明来源、许可证与替代方案

五、提交与评审要求

环节	要求
提交信息	格式 feat|fix|refactor|docs|test|chore(scope): 摘要，正文写动机与影响
单次 MR	变更不超过 　　 行（生成代码除外），单一主题可独立回滚
自测	单测覆盖新增逻辑分支，本地全量测试通过后再提 MR
评审	至少 　　 名评审人 approve；评审重点：正确性、边界、安全、可读性