服务端代码规范

通用服务端代码规范（语言无关，可用于 Go / Java / Node / Python 等）

1. 目标与原则

1.1 目标

• 提高代码可读性
• 保证代码一致性
• 降低维护成本
• 避免低级错误
• 支持团队协作与代码审查

1.2 核心原则

• 简单优先（KISS）
• 单一职责（SRP）
• 禁止魔法值
• 显式优于隐式
• 约定优于配置
• 可测试性优先

2. 项目目录结构规范

推荐分层结构（示例）：

project-root/
├── cmd/                # 启动入口
├── config/             # 配置文件
├── internal/
│   ├── controller/     # 接口层
│   ├── service/        # 业务逻辑
│   ├── repository/     # 数据访问层
│   ├── model/          # 数据模型
│   ├── middleware/     # 中间件
│   ├── dto/            # 请求/响应对象
│   └── util/           # 工具类
├── pkg/                # 可复用模块
├── docs/               # 文档
├── tests/              # 测试
├── logs/
└── main.go / app.js

禁止：

• 所有代码放在一个目录
• controller 直接操作数据库
• service 直接处理 HTTP

3. 命名规范

3.1 通用规则

• 使用英文
• 语义清晰
• 不使用拼音
• 不使用缩写（除非通用）

❌ bad：

a, b, data1, tmp, list2

✅ good：

userService
orderRepository
calculateTotalPrice

3.2 文件命名

• 小写 + 下划线
• 表意清晰

user_controller.go
order_service.go
auth_middleware.go

3.3 类 / 结构体命名

• 大驼峰（PascalCase）

UserService
OrderRepository
AuthMiddleware

3.4 方法命名

• 动词开头

GetUserById()
CreateOrder()
UpdatePassword()
DeleteAccount()

禁止：

doSomething()
handle()
process()

4. 代码风格规范

4.1 单函数长度

• 不超过 50 行
• 超过必须拆分

4.2 单函数职责

一个函数只做一件事：

❌ bad：

func registerUser() {
  validate()
  save()
  sendEmail()
  log()
}

✅ good：

func registerUser() {
  validateUser()
  createUser()
}

4.3 注释规范

必须注释的地方

• 复杂逻辑
• 公共方法
• 算法
• 边界处理

示例：

// CreateUser 创建新用户并校验手机号唯一性
func CreateUser(req CreateUserRequest) error {
}

禁止：

// i++
i++

5. 日志规范

5.1 日志级别

• DEBUG
• INFO
• WARN
• ERROR
• FATAL

5.2 日志内容必须包含

• 时间
• 请求 ID
• 用户 ID（如果有）
• 方法名
• 错误信息

示例：

ERROR | requestId=xxx | userId=123 | CreateOrder | db error: timeout

禁止：

print("error")

6. 异常与错误处理

6.1 禁止忽略错误

❌ bad：

result, _ := db.Query()

✅ good：

result, err := db.Query()
if err != nil {
    return err
}

6.2 错误必须包装业务语义

ErrUserNotFound
ErrOrderExpired
ErrPermissionDenied

禁止直接返回数据库错误给前端。

7. 接口（API）规范

7.1 RESTful 风格

动作	方法
查询	GET
新建	POST
更新	PUT
删除	DELETE

GET /api/users/{id}
POST /api/users
PUT /api/users/{id}
DELETE /api/users/{id}

7.2 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

错误示例：

{
  "code": 40001,
  "message": "User not found"
}

8. 参数校验规范

• 所有外部输入必须校验
• Controller 层校验参数合法性
• Service 层校验业务规则

例如：

• 空值
• 长度
• 格式
• 枚举值

9. 数据库规范

9.1 表命名

user
order
order_item

9.2 字段命名

id
user_id
created_at
updated_at
deleted_at

9.3 禁止

• SELECT *
• 在循环中查数据库
• 在 controller 层写 SQL

10. 安全规范

10.1 必须防御

• SQL 注入
• XSS
• CSRF
• 重放攻击

10.2 密码

• 必须加密存储（bcrypt / argon2）
• 禁止明文
• 禁止日志打印密码

11. 配置管理规范

• 配置与代码分离

• 不写死在代码中

• 区分环境：

  • dev
  • test
  • prod

12. 测试规范

12.1 单元测试覆盖率

• 核心逻辑必须测试
• service 层重点测试

12.2 测试命名

TestCreateUserSuccess
TestCreateUserFailWhenPhoneExists

13. Git 提交规范

13.1 Commit Message

格式：

type(scope): message

type：

• feat
• fix
• docs
• refactor
• test
• chore

示例：

feat(user): add user register api
fix(order): fix price overflow bug

14. Code Review 规范

必须检查：

• 是否遵守分层架构
• 是否有重复代码
• 是否有潜在空指针
• 是否有安全问题
• 是否有性能问题

15. 禁止行为清单

❌ Controller 直接操作数据库 ❌ 超过 100 行函数 ❌ magic number ❌ 无日志 ❌ 无错误处理 ❌ 无测试 ❌ 无文档 ❌ 明文密码 ❌ print 调试代码

16. 推荐工具

• 格式化工具：gofmt / prettier
• 静态检查：golangci-lint / sonarqube
• API 文档：Swagger / OpenAPI
• 日志：zap / logrus
• ORM：GORM / MyBatis / Prisma

17. 代码质量金字塔

安全性
稳定性
可维护性
可读性
可运行性

18. 附录：示例接口代码结构

Controller
  -> DTO
     -> Service
        -> Repository
           -> DB