不灭的焱

加密类型:SHA/AES/RSA下载Go
复合类型:切片(slice)、映射(map)、指针(pointer)、函数(function)、通道(channel)、接口(interface)、数组(array)、结构体(struct) Go类型+零值nil
引用类型:切片(slice)、映射(map)、指针(pointer)、函数(function)、通道(channel) Go引用

作者:AlbertWen  添加时间:2026-11-12 10:50:23  修改时间:2026-11-21 23:35:54  分类:04.GoFrame框架  编辑

目录

本版内容: 明确 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 文件内声明的空行

  1. package 声明后留 1 个空白行,再写 import 或其他声明。
  2. import 块与其后的类型、变量、常量或函数声明之间留 1 个空白行。
  3. 独立的 type、const、var 声明组之间建议留 1 个空白行。
  4. 多个相关常量使用同一个 const (...) 块,不需要每行空行。
  5. 顶层声明与函数之间保持 1 个空白行;不要连着留下 2 行以上空白行。
  6. 文件末尾保留一个换行符,避免多余空行。
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 版本升级强制规则

  1. 所有 Schema 变更都必须新增迁移文件,禁止修改已经在任一共享环境执行过的历史脚本。
  2. 文件命名:时间戳_业务模块_动作.sql;确保全局唯一。
  3. 新增字段优先兼容旧代码;避免部署瞬间要求新旧版本同时改变。
  4. 对大表加索引、改字段、数据回填,应评估锁表、执行时间和数据库负载。
  5. MySQL 某些 DDL 不具备通用的事务回滚能力,不能认为 Goose Down 能保证完整恢复。
  6. SQL 升级前应备份并验证恢复能力,演练生产版本的迁移路径。
  7. 迁移失败必须中止后续发布,不启动不兼容的新版本代码。
  8. 生产发布后出现问题,默认优先通过兼容性回退应用或新的前向 SQL 修复,而不是盲目 goose down。
  9. 数据初始化 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 工具加载。该文件为执行摘要,不应与本文发生冲突:

  1. 项目为模块化单体,禁止自动拆成微服务或为跨模块调用引入 RPC。
  2. cmd/server 仅承担应用启动、路由、配置、任务调度。
  3. modules/* 承担业务模型、流程、数据访问,禁止跨模块导入 internal。
  4. 新增功能优先复用模块现有 API、Logic、DAO,不能任意创建第二套平行分层。
  5. 新增定时任务应包含任务名、频率、超时、幂等、失败处理、监控及配置开关。
  6. 数据库 Schema 变化必须提交 Goose SQL 迁移,禁止只改结构体或让应用启动时默默改表。
  7. 增加/更改关键业务规则时,必须同步增加测试。
  8. 生成代码之前检查现有命名及目录,避免制造重复模型、无用接口和循环依赖。
  9. 所有金额使用安全的定点处理;时间和权限必须明确业务主体及所属时区。
  10. 生成的 .go 文件必须符合本文第 4 章排版要求:顶层函数之间恰好 1 个空行;左大括号不能另起一行;else 写 } else {;统一通过 gofmt。
  11. 产出代码后运行 make fmt && make vet && make lint && make test && make build(相应工具已安装前提下)。

12. 采用顺序(落地优先级)

第一阶段: 建立 go.work、cmd/server、业务模块公开入口、pkg/shared、统一路由、代码格式与单测。

第二阶段: 建立 db/migrations 与 Goose 发布流程,补充生产数据库升级验证和历史脚本不可修改规则。

第三阶段: 按真实需求增加 scheduler 和模块内 job;优先落地幂等、失败重试、超时和监控,不急于引入独立任务服务。

第四阶段: 持续完善跨模块契约、集成测试、审计、安全及 CI 门禁。

参考资料