From 866368537cb8e847bc40da15b350e758cc50096e Mon Sep 17 00:00:00 2001
From: kevin <kevin@lmve.net>
Date: Mon, 21 Sep 2026 20:28:41 +0800
Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E5=90=8E=E7=AB=AF=E5=BC=80?=
 =?UTF-8?q?=E5=8F=91=E8=A7=84=E8=8C=83=E6=96=87=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 说明目录结构与依赖方向
- 重点说明 internal/utils 的使用：ClientIP 取值规则与可信代理配置、RemoteIP、RandomString、新增工具函数流程
- 约定接口响应、数据库迁移、测试与提交流程
---
 docs/backend-development.md | 115 ++++++++++++++++++++++++++++++++++++
 1 file changed, 115 insertions(+)
 create mode 100644 docs/backend-development.md

diff --git a/docs/backend-development.md b/docs/backend-development.md
new file mode 100644
index 0000000..f6417b1
--- /dev/null
+++ b/docs/backend-development.md
@@ -0,0 +1,115 @@
+# 后端开发规范
+
+本文约定后端代码的组织方式与开发流程，重点说明通用工具模块 `internal/utils` 的使用。
+
+## 1. 目录结构
+
+`internal/` 按功能拆分模块，职责单一：
+
+```
+internal/
+├── api/          仅路由装配（公开/登录/管理员三组）
+├── auth/         注册、登录、JWT、鉴权中间件、个人资料
+├── user/         用户管理
+├── usergroup/    用户组管理
+├── note/         便签
+├── site/         站点信息
+├── httpx/        HTTP 公共能力：ErrorResponse、分页、ID 解析
+├── utils/        通用工具（与业务无关的公共函数）
+├── model/        数据库模型
+├── database/     连接、迁移、种子数据
+├── config/       配置加载与自动补全
+└── testutil/     测试公共环境（仅测试引用）
+```
+
+依赖方向：业务模块 → `httpx` / `utils` / `model`，禁止反向依赖；`api` 只做路由装配，不写业务逻辑。
+
+## 2. 通用工具模块 `internal/utils`
+
+### 使用原则
+
+- 只放**与具体业务无关**的公共函数；有业务语义的逻辑放在对应业务模块
+- 一个主题一个文件（如 `ip.go`、`random.go`），函数命名语义化
+- 新增函数必须附带同包单元测试（`*_test.go`）
+- 尽量无全局可变状态；无法避免时（如可信代理配置）提供 `SetXxx` 初始化函数、内部加锁保证并发安全，并在 `main.go` 启动时接线
+- `utils` 只允许依赖标准库与 gin，不得依赖 `model` 等业务包
+
+### 2.1 获取客户端 IP
+
+统一使用 `utils.ClientIP(c)`，**不要**直接使用 `c.ClientIP()` 或 `c.Request.RemoteAddr`——前者无法兼容多 CDN 且 gin 默认信任所有代理，后者拿到的是代理节点地址。
+
+```go
+ip := utils.ClientIP(c) // 业务取 IP 的唯一入口，如操作日志
+```
+
+取值规则：
+
+1. 先取直连地址；**只有直连地址属于可信代理时才会读取转发头**，否则直接返回直连地址（防止伪造）
+2. 按优先级依次尝试：`CF-Connecting-IP` → `True-Client-IP` → `Ali-CDN-Real-IP` → `X-Real-IP` → `X-Client-IP` → `Fastly-Client-IP` → `Forwarded`(RFC 7239) → `X-Forwarded-For`
+3. 链式头（`Forwarded`、`X-Forwarded-For`）从右往左取第一个非可信代理 IP，全部可信时取最左
+4. 每个候选值自动去引号、去端口并校验合法性，非法值跳过继续尝试下一个
+5. unix socket 连接视为可信（本地进程）
+
+可信代理通过配置项 `server.trusted_proxies` 设置（IP 或 CIDR 列表）：
+
+```yaml
+server:
+  # 留空表示不信任任何代理头；部署 CDN / 自建反代时填其回源网段
+  trusted_proxies:
+    - "173.245.48.0/20"   # 示例：Cloudflare 回源网段
+    - "127.0.0.1"
+```
+
+注意：`main.go` 启动时已同时调用 `utils.SetTrustedProxies` 与 `r.SetTrustedProxies`，业务代码**不要**重复调用或修改该配置。
+
+需要直连地址（审计、排障）时使用 `utils.RemoteIP(c)`，它不读取任何请求头。
+
+### 2.2 随机字符串
+
+安全敏感场景（初始密码、令牌等）统一使用 `utils.RandomString(n)`，内部使用 `crypto/rand` 且字符集去掉了易混淆字符；禁止用 `math/rand` 生成此类字符串。
+
+```go
+password, err := utils.RandomString(16)
+```
+
+### 2.3 新增工具函数的流程
+
+1. 判断是否属于与业务无关的公共逻辑
+2. 放入对应主题文件，或新建 `xxx.go` / `xxx_test.go`
+3. 涉及全局初始化时提供 `SetXxx`，并在 `main.go` 中调用（配置类需同时加入 `config` 校验与 `ConfigVersion` 升级）
+4. 运行 `gofmt -l . && go build ./... && go vet ./... && go test ./...`
+
+## 3. 接口规范
+
+- **响应文案一律英文**，统一错误响应 `httpx.ErrorResponse`，如 `invalid request`、`record not found`、`internal server error`、`unauthorized or session expired`
+- 分页参数用 `httpx.ParsePagination(c)`；路径 ID 用 `httpx.ParseID(c)`（用户组用 `usergroup` 内部的 `parseGroupID`，允许 id 0）
+- Swagger 注解：`@Summary` / `@Description` / `@Tags`（按权限取 `public` / `user` / `admin`）/ `@Security BearerAuth` / 401、403、500 失败响应；注解修改后执行 `go generate ./...` 重新生成 `docs/`
+- 路由按权限挂载：公开（`/health`、`/swagger`、`/auth/*`、`GET /site`）、需登录、仅管理员
+
+## 4. 数据库与迁移
+
+- 模型放在 `internal/model/`，表名遵循 GORM 默认复数
+- 迁移**只能追加**（`Version` 递增），禁止修改已发布的迁移；补数据、字段翻译等一次性操作同样通过新迁移完成
+- SQLite 为单连接串行写且不建外键；多对多关联表手动维护（参考 `user_group_members`）
+- 仅日期字段使用 `model.Date`（JSON 为 `YYYY-MM-DD`，未设置输出 `null`）
+- 状态字段沿用 `int8`（`status`）或字符串枚举（`gender`、`file operation`），取值定义在 `model` 包
+
+## 5. 测试与验证
+
+- 接口层测试使用 `internal/testutil`（临时库、鉴权路由、请求辅助），业务/工具测试放在对应包
+- 表驱动优先；涉及全局状态的测试用 `t.Cleanup` 复位
+- 提交前必须通过：
+
+```sh
+gofmt -l .
+go build ./...
+go vet ./...
+go test ./...
+```
+
+- 修改 Swagger 注解后额外执行：`go generate ./...`
+
+## 6. 提交规范
+
+- 提交信息使用简短中文标题，正文用要点列出改动
+- 一个提交只做一件事；重构与功能尽量分开