|
| 1 | +# 项目上下文:翻墙订阅链接服务 |
| 2 | + |
| 3 | +--- |
| 4 | + |
| 5 | +## 1. Go 编码规范 |
| 6 | + |
| 7 | +### 1.1. 语法与性能 |
| 8 | + |
| 9 | +* **语法糖**: 尽量尝试使用go新语法和语法糖,如泛型等, 根据go.mod上的go版本。 |
| 10 | +* **字符串拼接**: 对于多个字符串的拼接,必须使用 `strings.Builder` 来提升性能。 |
| 11 | +* **预分配内存**: 使用 `make` 创建 slice 或 map 时,应根据预估大小设置初始容量,以减少内存重新分配。 |
| 12 | +* **大 Slice 切片**: 从大 slice 中切取一小部分后,建议使用 `copy` 创建新 slice,以帮助垃圾回收器释放不再使用的内存。 |
| 13 | +* **JSON 标签**: 熟练使用 `json:"-"` 来忽略字段,以及 `json:"fieldName,omitempty"` 来忽略空值字段。 |
| 14 | +* **go协程**: 尽量使用go协程提高并发, 分析是否有必要使用到`chan`。 |
| 15 | +* **事务**: 事务内非必要不做查询操作。 |
| 16 | +* **命名**: 变量,常量,文件 等命名务必要简洁且规范, 同时避免使用单个字母的命名。 |
| 17 | + |
| 18 | +### 1.2. 并发安全 |
| 19 | + |
| 20 | +* **协程管理**: 推荐使用 `errgroup` 来管理一组协程的生命周期和错误。 |
| 21 | +* **Panic 处理**: 任何 `go` 启动的协程内部,都必须使用 `defer` 和 `recover` 来捕获潜在的 `panic`,防止主程序崩溃。 |
| 22 | +* **循环闭包**: 在 `for` 循环中启动协程,必须将循环变量作为参数传入,以避免闭包陷阱。 |
| 23 | +* **单次执行**: 使用 `sync.Once.Do` 确保配置加载等初始化操作只执行一次。 |
| 24 | +* **并发读写**: 读多写少的场景优先使用 `sync.RWMutex`。 |
| 25 | +* **数据竞争**: 使用协程时, 避免数据竞争和闭包陷阱,确保内存安全。 |
| 26 | + |
| 27 | +### 1.3. 健壮性与设计模式 |
| 28 | + |
| 29 | +* **依赖注入 (DI)**: 优先通过函数参数传递依赖(如数据库连接),严格避免在函数内部调用全局变量。 |
| 30 | +* **上下文 (Context)**: 所有可能阻塞或涉及 I/O 的函数,其第一个参数都应是 `context.Context`,用于控制超时和取消。 |
| 31 | +* **错误处理**: |
| 32 | + * 必须对所有可能返回 `error` 的函数进行检查。 |
| 33 | + * 查询数据库后,必须显式处理 `sql.ErrNoRows` 的情况。 |
| 34 | +* **Map 安全**: 读取 map 时,必须使用 `value, ok := m["key"]` 的双返回值形式进行安全判断。 |
| 35 | +* **空指针防御**: 对配置文件、反序列化等外部数据源保持警惕,做好 `nil` 检查。 |
| 36 | + |
| 37 | +### 1.4. 禁止事项 |
| 38 | + |
| 39 | +* **禁止 `fmt`**: 在业务逻辑代码中,使用项目配置的结构化日志库,禁止使用 `fmt` 包打印日志。 |
| 40 | +* **禁止滥用 `init`**: 尽量将初始化逻辑放在 `main` 函数或构造函数中。 |
| 41 | +* **禁止可变全局变量**: 避免使用任何可能在运行时被修改的全局变量。 |
| 42 | +* **注意 Map 无序**: 不要编写任何依赖 `for range` 遍历 `map` 顺序的代码。 |
| 43 | + |
| 44 | +## 7. 其他 |
| 45 | + |
| 46 | +* **redis使用**: 避免 缓存穿透、缓存击穿、缓存雪崩 等问题。 |
| 47 | +* 如果改动配置文件, 则必须同步以下文件: 配置事例文件位于目录下的`config.example.yaml`, 对应go代码文件`model/config/default.go`和`model/config/child.go`. |
| 48 | +* 善用`utils/tool.go`下的工具类,避免出现重复代码。 |
0 commit comments