目录
本版内容: 明确 Go 代码的空行与花括号规范、函数签名与参数换行、结构体/复合字面量、if/else/switch、导入分组、注释、编辑器自动格式化及 AI Coding 的格式要求;保留完整的 go.work 多模块、单体部署、GoFrame 分层、定时任务、Goose SQL 升级和质量门禁。
关键结论: 顶层函数之间 1 个空行(团队强制),{ 跟随声明同行(Go 语法强制),多行块右侧 } 独占一行(else 等语法除外),格式以 gofmt 为基础。
适用范围:GoFrame v2、Go Workspace(go.work)、单 Git 仓库、模块化单体架构(Modular Monolith)。
核心原则:一个 Git 仓库、多个 Go Module、一个后端可执行程序、一个统一部署单元。本项目不采用微服务、RPC 服务拆分或分布式服务注册。
说明:本文是统一规范文档,不拆分 GoFrame 工程规范和 Go 语言编码规范。 其中“必须”属于强制规则,“建议”属于团队推荐;违反 Go 语法的格式要求不得采用。示例域名
example.com/freight应替换为实际 Git 仓库模块路径;Go 版本、数据源类型、任务频率均须按实际环境确定。
1. 技术架构与边界
| 项目 | 约定 |
|---|---|
| 语言与框架 | Go + GoFrame v2 |
| 仓库 | 单仓库(Monorepo) |
| 模块 | go.work 管理多个 go.mod |
| 部署 | 只编译、启动 cmd/server 一个后端程序 |
| 子系统 | modules/crm、srm、pms、oms、fns |
| 路由 | 一个 HTTP 服务,统一注册子模块路由 |
| 定时任务 | 同一进程内使用 GoFrame gcron;统一注册、模块内执行 |
| SQL 版本升级 | 使用 Goose 统一执行版本化 SQL 迁移 |
| 数据 | 默认一个业务数据库,按模块前缀划分表名;数据库类型选定后统一 SQL 方言 |
| 共享代码 | pkg/shared 中明确职责的公共能力 |
| 工程规范 | gofmt / goimports / go vet / golangci-lint / 测试 / 顶层函数空行审查 |
Go Module 不等于微服务。 多个 go.mod 是代码及依赖边界,不是独立部署单元。不得为模块间调用引入 HTTP、RPC、消息队列等额外机制,除非业务本身确实需要异步消息。模块之间默认通过 Go 公共接口或公开函数协作。
2. 推荐项目目录结构
freight/
├── go.work # 多模块工作区
├── go.work.sum # 自动生成时纳入版本控制
├── .gitignore
├── .golangci.yml # 统一静态检查
├── Makefile # 测试、构建、检查统一命令
│
├── cmd/
│ └── server/ # 唯一可执行程序(独立 go.mod)
│ ├── go.mod
│ ├── go.sum
│ ├── main.go # 仅保留最小启动逻辑
│ ├── internal/
│ │ ├── bootstrap/ # 初始化、依赖装配、关闭资源
│ │ ├── router/ # 集中注册业务模块 HTTP 路由
│ │ ├── scheduler/ # 集中配置、注册和管理 cron 调度
│ │ └── middleware/ # 认证、授权、审计、追踪
│ └── manifest/
│ └── config/
│ └── config.yaml # 示例/非敏感配置,机密通过环境注入
│
├── modules/ # 业务模块,每个模块一个 go.mod
│ ├── crm/
│ │ ├── go.mod
│ │ ├── register.go # 公开的 HTTP 路由注册入口
│ │ ├── api/
│ │ │ └── v1/ # API DTO:Request / Response
│ │ ├── contract/ # 对其他业务模块公开的契约(按需创建)
│ │ └── internal/
│ │ ├── controller/ # HTTP 控制器
│ │ ├── service/ # 业务能力接口(按需)
│ │ ├── logic/ # 业务规则与流程编排
│ │ ├── dao/ # 数据访问(可用 GoFrame 生成)
│ │ └── model/ # 内部业务模型 / 数据对象
│ ├── srm/ # 供应商管理
│ ├── pms/
│ │ ├── go.mod
│ │ ├── register.go
│ │ ├── jobs.go # 对外提供定时任务的公开入口
│ │ ├── api/
│ │ └── internal/
│ │ ├── controller/
│ │ ├── logic/
│ │ ├── dao/
│ │ ├── model/
│ │ └── job/ # 报价有效期处理等业务任务
│ ├── oms/
│ │ ├── go.mod
│ │ ├── register.go
│ │ ├── jobs.go
│ │ └── internal/
│ │ └── job/ # 运输节点同步等业务任务
│ └── fns/ # 财务结算
│
├── pkg/
│ └── shared/
│ ├── go.mod
│ ├── errors/ # 公共错误表达及错误码
│ ├── pagination/ # 分页契约
│ ├── money/ # 金额与币种处理
│ └── lock/ # 跨实例锁(有需要时创建)
│
├── db/
│ ├── migrations/ # SQL Schema 版本迁移:同一库统一编号
│ │ ├── 202611120001_crm_init.sql
│ │ ├── 202611120002_pms_init.sql
│ │ └── 202611120003_oms_init.sql
│ ├── seeds/ # 可重复执行的初始化基础数据
│ └── manual/ # 受控运行的一次性修复/回填脚本
│
├── scripts/ # 构建、测试、部署脚本
├── tests/
│ └── e2e/ # 系统端到端测试(脚本或测试配置)
└── docs/
└── GoFrame项目开发与Go语言编码规范.md # 本文,唯一主规范文档
2.1 各目录的真实职责
cmd/server:唯一程序入口,负责启动 GoFrame HTTP 服务、加载配置、组装模块、启动定时任务。不得承载订单计算等业务规则。modules/<domain>:一个业务边界和一个 Go Module。业务逻辑、数据访问、任务实现均归属此模块。modules/<domain>/register.go:负责暴露公开的注册入口,避免入口程序越过internal访问模块私有实现。modules/<domain>/jobs.go:只有存在定时业务时才添加,用于安全地对外暴露任务执行入口。pkg/shared:真正稳定、跨业务的基础代码。禁止把全部业务 DTO 或 DAO 放进去。db/migrations:数据库 Schema 升级的唯一版本序列。单个数据库使用统一 Goose 迁移版本表,不允许多个模块共用同一迁移表却各自维护重复版本号。db/manual:回填和历史修复等可能需要审批的数据脚本,不等同于版本迁移。
目录精简规则: 初期不必创建空的 contract、job、lock 等目录;真实需要出现时再建。无须增加 apps/、worker/ 或多个后端二进制。cmd/server 中的 internal/scheduler 只是同一进程内的任务调度,不是独立 Worker 服务。
2.2 go.work 示例
以下以 Go 1.25 为示例,实际版本按项目统一的工具链版本修改:
// go.work
go 1.25
use (
./cmd/server
./modules/crm
./modules/srm
./modules/pms
./modules/oms
./modules/fns
./pkg/shared
)
go.work 方便本地引用各个模块,但不能替代各模块的 go.mod。每个模块仍需声明自己使用的依赖(包括相互依赖的本地模块),并按 CI 和发布流程验证。建议将工作区文件提交到单仓库。不要以“每个模块必须能够完全脱离这个 Monorepo 独立部署”为设计目标,否则会人为制造不必要的发布复杂度。
2.3 跨模块调用规范
Go 的 internal 规则限制外部导入。cmd/server 不应访问 modules/crm/internal/controller。由模块根目录公开受控入口,例如:
// modules/crm/register.go(示意)
package crm
import (
"github.com/gogf/gf/v2/net/ghttp"
"example.com/freight/modules/crm/internal/controller"
)
func RegisterRoutes(group *ghttp.RouterGroup) {
group.Bind(controller.NewCustomer())
}
cmd/server/internal/router 再调用 crm.RegisterRoutes(group)。NewCustomer() 是示例构造函数,需根据实际项目实现。跨业务模块使用独立的公开接口/契约,避免循环依赖;不允许越过公开入口调用别的模块 internal 或 DAO。
3. Go 命名与基本编码约定
| 对象 | 约定 | 示例 |
|---|---|---|
| 包名 | 小写短单词,不用下划线 | order, customer |
| Go 文件 | 小写 snake_case(团队约定) | order_service.go |
| 导出类型、方法、函数 | PascalCase | OrderService, CreateOrder |
| 非导出类型、方法、函数 | camelCase | validateOrder |
| ID / URL / HTTP / API 等缩写 | 遵循 Go initialism 习惯 | customerID, apiURL, HTTPServer |
| 常量 | MixedCaps,不用 Java 式全大写下划线 | MaxRetryCount, orderTimeout |
| JSON tag | 默认 camelCase | customerId, orderNo |
| 数据库表/列 | snake_case | oms_order, customer_id |
| 测试 | _test.go |
order_service_test.go |
- 所有代码必须通过
gofmt;使用goimports管理导入分组。 - 导出 API 和容易误解的规则使用 Go Doc 注释,以被描述的标识符开头。
- 只写有明确职责的类型和方法。不要为了模仿 Java 强制为每个 Service 定义接口。
- 避免
utils、common、helper等泛化包;如果确实需要,应说明具体能力边界。 - 建议单函数控制在约 50 行以内、嵌套不超过 3 层,这只是代码评审提示,不是 Go 官方硬限制。
- 尽可能提前返回,减少嵌套。不要刻意为了“行数达标”拆出没有业务意义的小函数。
示例:
type OrderStatus string
const (
OrderStatusPending OrderStatus = "pending"
OrderStatusConfirmed OrderStatus = "confirmed"
OrderStatusCancelled OrderStatus = "cancelled"
)
type CreateOrderReq struct {
CustomerID int64 `json:"customerId"`
ProductID int64 `json:"productId"`
Remark string `json:"remark"`
}
3.1 Context 传递
- 数据库、外部 HTTP、文件 I/O 等可能阻塞的业务函数以
ctx context.Context为第一个参数。 - 下游继续传递
ctx,不得无故用context.Background()替代。 - 不在普通业务结构体中长期保存
Context。 context.WithTimeout创建的取消函数必须调用,通常使用defer cancel()。
3.2 错误与日志
- 不忽略重要错误,不用
panic表示常规业务失败。 - 使用
fmt.Errorf("load order %d: %w", id, err)保留原始错误链。 - 参数错误、业务状态错误、权限错误、资源不存在、数据库系统错误应在统一错误体系中区分。
- 错误在下层携带上下文、在 API 边界统一转换与记录,避免每层重复打印同一错误。
- 日志关联
traceID、orderID等业务键;不记录密码、令牌和敏感字段。
func (s *OrderService) Load(ctx context.Context, orderID int64) (*Order, error) {
if orderID <= 0 {
return nil, ErrInvalidOrderID
}
order, err := s.repo.GetByID(ctx, orderID)
if err != nil {
return nil, fmt.Errorf("load order %d: %w", orderID, err)
}
return order, nil
}
4. Go 代码排版与语法格式规范(团队强制)
本章优先级最高: 先保证 Go 语法正确,再使用
gofmt/goimports统一格式,最后用人工评审或附加规则约束gofmt不强制处理的部分。不要照搬 Java、C# 的 Allman 大括号风格。
4.1 规范优先级与适用范围
| 等级 | 定义 | 示例 | 验证方式 |
|---|---|---|---|
| MUST(必须) | Go 语法、编译与安全正确性 | { 不得违规换行,错误不得被无故忽略 |
编译、gofmt、go vet、测试 |
| TEAM(团队强制) | 本项目统一的代码审查规则 | 两个顶层函数之间保留 1 个空行 | Code Review;按需自定义检查 |
| SHOULD(建议) | 避免过度机械化的可维护性建议 | 函数控制在约 50 行内 | 人工评审 |
4.2 花括号 {} 位置(重点)
规则:函数、方法、if、for、switch、select 的左大括号 { 必须写在声明/控制语句末尾,不能单独换到下一行。 这是 Go 的语法和自动分号插入机制决定的,不是团队风格选项。多行代码块中的右大括号 } 独占一行;else 是例外,必须写作 } else {。
❌ 错误(在 Go 中不可作为有效的函数声明格式):
func CreateOrder(ctx context.Context) error
{
return nil
}
✅ 正确:
func CreateOrder(ctx context.Context) error {
return nil
}
控制语句同理:
if err != nil {
return err
} else {
return nil
}
团队补充: 业务函数和控制块即使只有一个语句,也采用多行,不刻意写成 if ok { return nil }。但 struct{} 空结构体、interface{}(老代码,优先 any)、map[string]struct{}{}、复合字面量等语法不属于必须“把每一对 {} 强行拆开”的范畴。
4.3 函数与函数之间必须空 1 行(重点)
同一个文件中,两个顶层函数或方法声明之间保留恰好 1 个空白行。如果下一个函数带有 Go Doc 注释,空白行放在前一个函数结束位置与注释之间,注释与被注释的函数之间不允许空行。
✅ 正确:
func CreateOrder(ctx context.Context, input CreateOrderInput) error {
return validateOrder(input)
}
// CancelOrder cancels an existing order.
func CancelOrder(ctx context.Context, orderID int64) error {
return nil
}
❌ 不推荐(相邻顶层函数没有空白行):
func CreateOrder() {}
func CancelOrder() {}
❌ 不推荐(在注释与函数声明之间添加空行):
// CreateOrder creates an order.
func CreateOrder() {}
注意:gofmt 不会可靠地为相邻函数自动插入空白行。 它可以整理现有多余空白,但这一条属于团队约定,需要评审或项目自定义检查,不能仅靠 gofmt 保证。
4.4 文件内声明的空行
package声明后留 1 个空白行,再写import或其他声明。import块与其后的类型、变量、常量或函数声明之间留 1 个空白行。- 独立的
type、const、var声明组之间建议留 1 个空白行。 - 多个相关常量使用同一个
const (...)块,不需要每行空行。 - 顶层声明与函数之间保持 1 个空白行;不要连着留下 2 行以上空白行。
- 文件末尾保留一个换行符,避免多余空行。
package order
import (
"context"
"fmt"
)
const maxRetryCount = 3
type Service struct {
repo Repository
}
func (s *Service) Create(ctx context.Context) error {
return fmt.Errorf("not implemented")
}
上述缩进最终以
gofmt输出为准,Go 标准缩进由 Tab 处理,不应人为用空格强行对齐缩进层级。
4.5 函数内部的空行
函数中的空行用来分隔逻辑阶段,不要逐行加空行,也不要让整段业务逻辑完全粘连。
建议将“参数校验 / 数据读取 / 规则处理 / 数据写入 / 结果返回”适当分段:
func (s *OrderService) Cancel(ctx context.Context, orderID int64) error {
if orderID <= 0 {
return ErrInvalidOrderID
}
order, err := s.repo.GetByID(ctx, orderID)
if err != nil {
return fmt.Errorf("get order %d: %w", orderID, err)
}
if order.Status == OrderStatusCancelled {
return ErrAlreadyCancelled
}
return s.repo.UpdateStatus(ctx, orderID, OrderStatusCancelled)
}
- 连续且紧密相关的赋值语句不必强制逐行空行。
if err != nil应紧跟产生err的调用,二者中间不要人为插入空行。- 相关的 guard clauses(提前返回)可以按实际语义分段。
return前不强制必须空一行;只有当它与前段逻辑确实需要视觉分组时才加。- 不要在代码块的首条或末条语句与
{/}之间增加空白行。
4.6 if / else / for / switch / select 的格式
if order == nil {
return ErrOrderNotFound
}
if order.Status == OrderStatusCancelled {
return ErrAlreadyCancelled
} else if order.Status == OrderStatusCompleted {
return ErrOrderCompleted
} else {
return nil
}
for _, item := range items {
if err := process(item); err != nil {
return err
}
}
switch status {
case OrderStatusPending:
return handlePending()
case OrderStatusConfirmed:
return handleConfirmed()
default:
return ErrUnsupportedStatus
}
else/else if必须在上一个}同行,写为} else {、} else if ... {。switch分支后不必显式break;仅在确有需要时使用fallthrough。- 不给
if条件加无意义的小括号:写if ok {,不写if (ok) {。 - 不在单个
case中堆积过多业务逻辑;复杂分支提取业务函数。 select和通道操作必须考虑取消、关闭与超时。
4.7 结构体、接口和复合字面量
多行 struct / interface 声明按 Go 格式自然换行;字段上的 JSON / DB tag 与字段同行。
type Order struct {
ID int64 `json:"id"`
CustomerID int64 `json:"customerId"`
Status OrderStatus `json:"status"`
CreatedAt time.Time `json:"createdAt"`
}
type OrderReader interface {
GetByID(ctx context.Context, id int64) (*Order, error)
}
var visited = map[int64]struct{}{}
多行复合字面量最后一个元素保留尾逗号:
order := Order{
ID: 1001,
CustomerID: 2002,
Status: OrderStatusPending,
}
fields := []string{
"order_no",
"customer_id",
"status",
}
简单字面量可以在一行,按可读性决定,如 point := Point{X: 1, Y: 2};不要强制对每一对 {} 换行。
4.8 函数声明、参数和调用的换行
- 简短声明优先单行:
func GetByID(ctx context.Context, id int64) (*Order, error) {。 - 参数过多应先考虑收敛为输入结构体,而不是单纯换成多行。
- 长参数列表或长函数调用允许按
gofmt兼容的语法换行;多行实参列表要有结尾逗号。 - 不人为要求函数签名必须换行,避免小函数占用过多屏幕空间。
func (s *QuotationService) Create(
ctx context.Context,
input CreateQuotationInput,
) (*Quotation, error) {
return s.repo.Create(ctx, input)
}
result, err := service.Create(
ctx,
CreateQuotationInput{
CustomerID: 1001,
ProductID: 2002,
},
)
4.9 import 分组与别名
统一按标准库 / 第三方包 / 本项目模块包划分,中间空 1 行。使用 goimports -local example.com/freight -w . 可将本项目导入分到第三组;正式使用时把示例模块前缀换成实际仓库路径。
import (
"context"
"fmt"
"time"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/os/gcron"
"example.com/freight/modules/crm"
"example.com/freight/modules/oms"
)
- 禁止无意义的导入别名、
.导入。 _导入只用于明确的注册副作用,例如数据库驱动。- 避免将 import、类型和函数全部写到同一紧凑段落。
4.10 缩进、行长、空格和对齐
- 所有
.go文件在提交前运行gofmt。Go 使用 Tab 缩进,编辑器可以配置 Tab 的显示宽度。 - 不手动用大量空格对齐结构体字段或赋值号;交给
gofmt。 - 建议行宽尽量不超过 120 个字符,但不为满足行宽而牺牲语义,不设“一超就禁止合并”的绝对限制。
- 运算符两侧、逗号后按
gofmt自动格式化,不自创空格风格。 - 不使用行尾分号,除
for三段式等 Go 语法确实需要的位置。
4.11 注释与 TODO
导出标识符使用 Go Doc 风格,注释紧邻定义且以名称开头,允许中文解释业务规则:
// CreateOrder 创建货运订单,并验证订单所属业务主体。
func CreateOrder(ctx context.Context, input CreateOrderInput) error {
// 业务主体必须从可信的授权上下文中确认,不能仅信任请求字段。
return nil
}
- 注释优先解释为什么这样做、限制和业务规则,而不是复述代码。
- 单行简单逻辑不强制每行写注释。
TODO建议带任务编号或负责人,完成后删除;不要长期积累无主 TODO。- 公共接口、状态机、金额换算、跨业务主体权限等关键规则必须有足够的注释或设计说明。
4.12 变量和常量声明
- 函数内优先使用清晰、就近的变量声明;类型明显时可用
:=。 - 不重复声明已存在的包级变量;避免遮蔽重要变量导致误用。
- 避免把运行时配置写成大量硬编码常量。
- 字符串状态和错误码应集中定义具名常量或专门类型。
const (
orderStatusPending OrderStatus = "pending"
orderStatusConfirmed OrderStatus = "confirmed"
)
如果常量供模块外使用,应改为
OrderStatusPending等导出名称;是否导出应由调用方需求决定。
4.13 错误处理的排版与规范
order, err := s.repo.GetByID(ctx, orderID)
if err != nil {
return nil, fmt.Errorf("get order %d: %w", orderID, err)
}
if order == nil {
return nil, ErrOrderNotFound
}
return order, nil
err检查紧跟调用;不要故意插入无关日志、赋值或空行。- 不丢弃错误(明确允许忽略的情形应说明原因)。
fmt.Errorf包装根因使用%w,便于errors.Is/errors.As。- 不在每一层打印重复日志;GoFrame HTTP 入口或统一中间件负责统一转换返回值。
- 不使用
panic表示“订单不存在”“报价已过期”等正常业务情况。
4.14 函数设计与方法接收者
- 函数名使用动词表达动作:
CreateOrder、CancelOrder、CalculateFreight。 - 单函数仅承担一个明确职责;优先使用提前返回,减少多级嵌套。
- 方法接收者统一短名,类型使用同一接收者名称,如
(s *OrderService);不使用this、self。 - 需要修改对象、避免大结构体复制或保持方法集一致时优先指针接收者。
context.Context作为涉及 IO 的函数首参数;error作为返回值的最后一个返回项。- 能用具体类型就不必为每个 Service 创建空泛接口;接口通常由调用方的真实需求驱动。
4.15 GoFrame 框架风格约束
- GoFrame API 的 Request / Response 定义统一存放在各模块的
api/v1等目录。 - Controller 仅做接口适配、鉴权入口和响应转换;业务状态转换与事务边界放在 Logic / Service。
- 使用 GoFrame
gerror、glog、gdb、gcron时遵循官方 API,不编造框架不存在的方法。 - GoFrame 生成的 DAO / Model 文件遵守生成器输出,不手动更改生成代码格式或字段;自定义逻辑写在非生成文件中。
- 不因为使用 GoFrame 而绕过 Go 标准库的
context.Context、errors.Is等通用约定。
4.16 编辑器配置与自动格式化
建议所有开发者开启保存时格式化,最基本的命令:
# 统一格式;针对指定 Go 文件或目录执行 gofmt -w . # 整理 import(需事先安装;按实际模块路径替换示例前缀) goimports -local example.com/freight -w . # 检查语法及常见问题 go vet ./...
gofmt -w . 和 goimports -w . 是在当前目录树处理文件,运行前应确认工作区根目录没有不希望改动的生成代码;CI 中应以检查模式验证,而不是暗中修改源代码。go vet ./... 在多 Module 仓库要进入每个模块运行。
4.17 提交前代码风格自检清单
- 左大括号在控制语句/函数声明末尾,
else使用} else {。 - 顶层函数之间恰好 1 个空行;注释与声明相邻。
- 每个多行函数体、
if、for、switch的右大括号独占一行。 - 没有为了“所有大括号换行”改坏 Go 语法;复合字面量按
gofmt格式化。 - 代码通过
gofmt和goimports;import 分组一致。 -
err未无故丢弃,错误链保留上下文。 - 控制逻辑使用早返回;函数职责清晰,不深度嵌套。
- 关键业务规则、金额、权限、事务、并发均有合理验证。
5. GoFrame 业务分层约定
请求流:HTTP → Controller → Logic/Service → DAO → Database。
| 层级 | 可以做 | 不应该做 |
|---|---|---|
| API | 请求响应 DTO、参数标签 | SQL、业务规则 |
| Controller | 接口适配、校验入口、响应转换 | 直接操作数据库 |
| Service | 稳定业务能力接口,按需使用 | 为了形式而层层转发 |
| Logic | 状态机、规则校验、业务编排 | 依赖 HTTP 控制器 |
| DAO | 数据查询、持久化、参数化 SQL | 决定业务审批规则 |
| Model | 实体和内部数据对象 | 依赖 Controller |
| Job | 定时触发后的业务任务执行 | 自行决定全局任务计划或重复初始化服务 |
GoFrame 的 service / logic 分层可以使用,但允许依据实际规模简化。最重要的是明确业务边界、避免循环依赖、避免重复封装。
跨模块业务调用优先使用公开契约,并确保依赖方向稳定。禁止直接复用其他模块的数据库访问层。对于确实需要跨模块事务的场景,必须明确统一事务边界,避免各业务模块自行开启互不关联的事务。
6. 数据库与事务编码规范
- 所有用户输入参与 SQL 时必须使用参数绑定,不通过字符串拼接构建 SQL。
- 常规 CRUD 优先使用 GoFrame ORM / DAO;复杂查询允许使用参数化原生 SQL,不需要强行转成难读的链式调用。
- 重要操作设置事务边界,尤其是订单、费用、状态任务一并修改的场景。
- 财务金额使用十进制定点处理或最小货币单位整数;不要使用
float64进行金额计算。 - 时间使用
time.Time,跨系统明确时区、存储标准和展示标准。 - SQL 表、列统一
snake_case,例如oms_order、crm_customer;状态字段尽量定义显式枚举规则。 - 多业务主体必须在查询、更新、导出和审计中进行数据归属和权限检查,不能仅靠前端传入
company_id限制数据访问。
GoFrame 事务示意:
err := g.DB().Transaction(ctx, func(ctx context.Context, tx gdb.TX) error {
if _, err := tx.Ctx(ctx).Insert("oms_order", orderData); err != nil {
return fmt.Errorf("create order: %w", err)
}
if _, err := tx.Ctx(ctx).Insert("oms_order_fee", feeData); err != nil {
return fmt.Errorf("create order fee: %w", err)
}
return nil
})
以上是简化示意,实际代码需要准备 orderData、feeData 和合法的 ctx,并按业务检查事务失败情况。
7. 定时任务规范(新增重点)
7.1 设计原则
统一注册,模块执行,仍然只部署一个后端程序。
cmd/server/internal/scheduler:保存执行周期、开关、任务名称及统一注册逻辑。modules/pms/internal/job:处理报价到期、产品价格失效等 PMS 任务。modules/oms/internal/job:处理运输节点同步、订单履约超时等 OMS 任务。modules/fns/internal/job:处理应收逾期提醒等 FNS 任务。modules/<domain>/jobs.go:公开可调用任务入口,供服务端调度器调用。
不要把所有业务任务写进 cmd/server/internal/scheduler。也不要让业务模块导入 cmd/server:应用入口依赖业务模块,业务模块不依赖应用入口。
7.2 gcron 注册示例
GoFrame gcron 使用六段表达式:秒 分 时 日 月 星期,区别于常见的五段 Unix crontab。下面示例为每 5 分钟执行一次:
// cmd/server/internal/scheduler/scheduler.go
package scheduler
import (
"context"
"fmt"
"github.com/gogf/gf/v2/frame/g"
"github.com/gogf/gf/v2/os/gcron"
"example.com/freight/modules/pms"
)
func Register(ctx context.Context) error {
_, err := gcron.AddSingleton(
ctx,
"0 */5 * * * *",
func(jobCtx context.Context) {
if err := pms.ExpireQuotations(jobCtx); err != nil {
g.Log().Errorf(jobCtx, "expire quotations: %v", err)
}
},
"pms_expire_quotations",
)
if err != nil {
return fmt.Errorf("register quotation expiry task: %w", err)
}
return nil
}
其中 pms.ExpireQuotations(ctx) 是由 PMS 模块自行实现的公开函数,例如在 modules/pms/jobs.go 中将调用委托给 internal/job,而 internal/job 继续调用该模块的 Logic/Service。gcron 调度器不应直接写 SQL 处理报价业务。
7.3 定时任务必须遵守的规则
| 事项 | 强制要求 |
|---|---|
| 任务标识 | 全局唯一、固定命名,如 pms_expire_quotations |
| 配置 | cron 表达式、是否启用、运行时区可配置 |
| 重叠执行 | 长任务优先防重入,必要时持久化锁 |
| 幂等 | 重试或重复触发不能重复核销、发通知或改状态 |
| 超时 | 任务必须有超时/取消能力 |
| 日志 | 记录开始、结束、耗时、成功/失败、业务数量 |
| 失败处理 | 区分可重试与不可重试;必要时发出告警 |
| 中断恢复 | 关键任务保存进度、游标、批次或任务状态 |
| 上线管理 | 新增任务必须经过测试、配置审核和发布确认 |
gcron.AddSingleton 只防止同一进程内任务重叠。即使不采用微服务,未来一个服务启动两个实例仍会分别触发 cron;涉及资金、库存、舱位、推送等任务时,需要数据库/Redis 锁、专门的调度实例或数据库任务认领机制。任务可靠性不能仅靠进程内定时器保证。
7.4 建议的初始任务清单(示例)
| 模块 | 任务 | 可能的频率 | 注意事项 |
|---|---|---|---|
| PMS | 检查报价有效期 | 每 5 分钟 | 幂等更新,仅处理到期记录 |
| OMS | 同步运输节点 | 每 10 分钟 | 增量游标、接口限流、重试 |
| OMS | 检查异常/超时订单 | 每小时 | 不重复产生异常或通知 |
| FNS | 应收账龄提醒 | 每天 | 按公司时区、避免重复提醒 |
| CRM | 线索待跟进提醒 | 每天 | 控制提醒频率、权限校验 |
以上仅是业务场景示例,不是确定的生产频率。启动时应按配置开关注册任务,避免测试/预发环境误调用正式业务外部接口。
8. SQL 版本升级规范(新增重点)
8.1 选型与目录
推荐 pressly/goose,SQL 脚本可读、版本可追踪、支持 MySQL / PostgreSQL 等多种数据库。对于当前 GoFrame 项目,SQL 升级由部署流程执行,而不是 HTTP 服务启动后随意执行 DDL。
db/
├── migrations/
│ ├── 202611120001_crm_init.sql
│ ├── 202611120002_pms_init.sql
│ ├── 202611120003_oms_init.sql
│ └── 202611120004_fns_add_invoice_status.sql
├── seeds/
│ └── currencies.sql
└── manual/
└── 20261112_fix_legacy_customer_code.sql
- 一个物理数据库 + 一张 Goose 版本记录表 + 一套全局递增/时间戳版本号。
- 用文件名中的
crm/pms/oms标识归属,维护权限归业务模块负责人,但迁移执行必须集中协调。 - 不要在同一个数据库里对不同业务目录分别执行默认 Goose 迁移,而复用同一版本记录表并产生编号冲突。
- 若项目确实同时支持 MySQL 与 PostgreSQL,不要让同一份方言特定 SQL 同时作用于两种数据库;需按数据库种类分目录和流水线执行。
8.2 SQL 迁移示例(MySQL 8)
文件:db/migrations/202611120001_crm_init.sql
-- +goose Up
CREATE TABLE crm_customer (
id BIGINT NOT NULL AUTO_INCREMENT,
customer_name VARCHAR(200) NOT NULL,
created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
PRIMARY KEY (id)
);
-- +goose Down
DROP TABLE crm_customer;
说明: 这个 Down 仅示范 Goose 语法,生产环境如已有客户数据,严禁直接执行会删除数据的回滚。实际变更优先采用可兼容的前向修复;删除列、删表等应有独立审批、备份及影响验证。
8.3 Goose 命令示例
安装工具(CI 建议固定具体版本):
go install github.com/pressly/goose/v3/cmd/goose@latest
把连接凭据放在受控环境变量中,避免放入 Git、脚本或日志。以下使用 Goose 官方支持的 GOOSE_DRIVER 和 GOOSE_DBSTRING:
# 环境变量示例,真实 DSN 从密钥管理系统注入 export GOOSE_DRIVER=mysql export GOOSE_DBSTRING='user:password@tcp(127.0.0.1:3306)/freight?parseTime=true' # 查看待执行状态 goose -dir db/migrations status # 执行升级 goose -dir db/migrations up # 查看当前数据库迁移版本 goose -dir db/migrations version
注意:上述脚本在仓库根目录执行。示例 DSN 仅用于演示格式;真实生产凭据不应写入版本库或终端共享记录。
8.4 SQL 版本升级强制规则
- 所有 Schema 变更都必须新增迁移文件,禁止修改已经在任一共享环境执行过的历史脚本。
- 文件命名:
时间戳_业务模块_动作.sql;确保全局唯一。 - 新增字段优先兼容旧代码;避免部署瞬间要求新旧版本同时改变。
- 对大表加索引、改字段、数据回填,应评估锁表、执行时间和数据库负载。
- MySQL 某些 DDL 不具备通用的事务回滚能力,不能认为 Goose
Down能保证完整恢复。 - SQL 升级前应备份并验证恢复能力,演练生产版本的迁移路径。
- 迁移失败必须中止后续发布,不启动不兼容的新版本代码。
- 生产发布后出现问题,默认优先通过兼容性回退应用或新的前向 SQL 修复,而不是盲目
goose down。 - 数据初始化
seeds、生产数据纠正manual、Schema 迁移migrations的执行权限与流程必须分开。
8.5 推荐部署顺序
代码合并 ↓ 格式 / Lint / 单测 / 集成测试 ↓ 构建单一 server 二进制 ↓ 在与生产一致的测试库验证 SQL 迁移 ↓ 生产数据库备份、变更审核 ↓ 执行 goose up(统一且仅执行一次) ↓ 验证数据库版本和关键表结构 ↓ 发布新 server 二进制 ↓ 检查 API、定时任务状态、日志和关键业务指标
如涉及不兼容 Schema,应拆成“扩展字段 → 代码兼容迁移 → 数据回填 → 停止旧字段依赖 → 后续版本清理”多阶段,不要强行一次执行。
9. 安全、权限与跨业务主体规则
- 客户、订单、产品、财务、合同等业务数据应明确归属主体,服务端独立校验权限。
company_id之类的隔离条件必须由认证上下文和授权规则确定,不应完全信任用户提交的字段。- 敏感操作有审计记录;留存操作人、时间、操作对象和前后状态。
- 统一错误映射,不把数据库 SQL、堆栈、内部路径直接返回给终端用户。
- 对外部系统回调设置鉴权、签名校验、时间窗和幂等控制。
- 财务核销、订单确认、库存/舱位分配必须考虑并发控制和重复提交。
10. 单元测试、集成测试、质量门禁
- 每个业务 Go Module 的单元测试与代码同目录,文件名
*_test.go;推荐表驱动测试。 - 核心业务状态机至少覆盖成功、非法状态转换、并发、重复请求、权限不足。
- 对 DAO / SQL 进行真实数据库集成测试,并对
db/migrations做迁移测试。 - CI 必须运行:
gofmt/goimports、go vet、golangci-lint、go test。 - 合并 PR 时通过安全扫描,禁止硬编码密码、令牌、云密钥。
建议 .golangci.yml(v2):
version: "2"
linters:
default: standard
enable:
- errorlint
- gocritic
- gosec
- misspell
- revive
formatters:
enable:
- gofmt
- goimports
run:
timeout: 5m
tests: true
在 go.work 工作区根目录不应该假设 go test ./... 能遍历所有子 Module。应进入每个有 go.mod 的目录执行命令。一个简单的 Makefile 例子:
MODULES := cmd/server modules/crm modules/srm modules/pms modules/oms modules/fns pkg/shared .PHONY: test vet lint fmt build test: @for mod in $(MODULES); do \ (cd $$mod && go test ./...) || exit 1; \ done vet: @for mod in $(MODULES); do \ (cd $$mod && go vet ./...) || exit 1; \ done lint: @for mod in $(MODULES); do \ (cd $$mod && golangci-lint run ./...) || exit 1; \ done fmt: @for mod in $(MODULES); do \ (cd $$mod && golangci-lint fmt ./...) || exit 1; \ done build: cd cmd/server && go build -o ../../bin/freight-server .
11. AI Coding 开发约定
本文是唯一主规范;可以将本章节的核心规则提取到项目根目录 AGENTS.md 供 AI Coding 工具加载。该文件为执行摘要,不应与本文发生冲突:
- 项目为模块化单体,禁止自动拆成微服务或为跨模块调用引入 RPC。
cmd/server仅承担应用启动、路由、配置、任务调度。modules/*承担业务模型、流程、数据访问,禁止跨模块导入internal。- 新增功能优先复用模块现有 API、Logic、DAO,不能任意创建第二套平行分层。
- 新增定时任务应包含任务名、频率、超时、幂等、失败处理、监控及配置开关。
- 数据库 Schema 变化必须提交 Goose SQL 迁移,禁止只改结构体或让应用启动时默默改表。
- 增加/更改关键业务规则时,必须同步增加测试。
- 生成代码之前检查现有命名及目录,避免制造重复模型、无用接口和循环依赖。
- 所有金额使用安全的定点处理;时间和权限必须明确业务主体及所属时区。
- 生成的
.go文件必须符合本文第 4 章排版要求:顶层函数之间恰好 1 个空行;左大括号不能另起一行;else写} else {;统一通过gofmt。 - 产出代码后运行
make fmt && make vet && make lint && make test && make build(相应工具已安装前提下)。
12. 采用顺序(落地优先级)
第一阶段: 建立 go.work、cmd/server、业务模块公开入口、pkg/shared、统一路由、代码格式与单测。
第二阶段: 建立 db/migrations 与 Goose 发布流程,补充生产数据库升级验证和历史脚本不可修改规则。
第三阶段: 按真实需求增加 scheduler 和模块内 job;优先落地幂等、失败重试、超时和监控,不急于引入独立任务服务。
第四阶段: 持续完善跨模块契约、集成测试、审计、安全及 CI 门禁。
参考资料
- Effective Go: https://go.dev/doc/effective_go
- Go Code Review Comments: https://go.dev/wiki/CodeReviewComments
- Go Modules / Workspaces: https://go.dev/ref/mod
- Go FAQ(Go 大括号为什么不能另起一行): https://go.dev/doc/faq
gofmt官方说明: https://pkg.go.dev/cmd/gofmt- Go 语言规范(自动分号): https://go.dev/ref/spec
- GoFrame gcron: https://pages.goframe.org/en/docs/components/os-gcron
- GoFrame cron 表达式: https://pages.goframe.org/en/docs/components/os-gcron-pattern
- Goose SQL migration: https://pressly.github.io/goose/documentation/annotations/
- Goose CLI: https://pressly.github.io/goose/documentation/cli-commands/
- golangci-lint v2: https://golangci-lint.run/docs/configuration/file/