Go 语言命名与目录结构规范全解

Go 的「规范」有三大权威来源，按优先级：

特殊后缀（Go 工具链识别）

包名三大铁律

核心规则

声明风格

// 函数内优先用短声明 :=
func handler(w http.ResponseWriter, r *http.Request) {
    userID := r.FormValue("id")   // 局部短名
    users, err := repo.List(r.Context())
    if err != nil { /* err 是约定名 */ }

    var total int            // 包级/零值/需显式类型时用 var
    const timeout = 30 * time.Second
}

// 普通常量：驼峰，导出大写
const (
    MaxRetries = 3
    DefaultTimeout = 30 * time.Second
)

// 枚举：iota 自增，首值带类型
type OrderStatus int
const (
    StatusPending OrderStatus = iota   // 0
    StatusPaid                               // 1，继承 OrderStatus 类型
    StatusShipped                            // 2
    StatusDone                               // 3
)

// 需要「跳过值/位标志」时也用 iota
const (
    Read  Perm = 1 << iota   // 1
    Write                          // 2
    Exec                           // 4
)

// 构造 + getter/setter（Go 风格，无 Get 前缀）
type User struct { name string }

func NewUser(name string) *User {   // 构造函数
    return &User{name: name}
}
func (u *User) Name() string { return u.name }      // getter：无 Get
func (u *User) SetName(n string) { u.name = n }  // setter

// error 永远最后
func GetUser(ctx context.Context, id int64) (*User, error) {
    if id <= 0 {
        return nil, fmt.Errorf("invalid id %d", id)
    }
    // ...
}

// ✅ 类型名即语义，不叫 UserStruct / UserModel
type User struct {
    ID        int64  `json:"id" db:"id"`        // 导出字段大写
    Name      string `json:"name"`
    email     string                                // 不导出：仅包内
    CreatedAt time.Time `json:"created_at"`
}

// 构造函数返回指针（结构体较大或需共享状态时）
func NewUser(name string) *User {
    return &User{Name: name, CreatedAt: time.Now()}
}

// 单方法接口 → -er 后缀（来自方法名）
type Reader interface { Read(p []byte) (int, error) }
type Writer interface { Write(p []byte) (int, error) }
type Stringer interface { String() string }
type Closer interface { Close() error }

// 小接口组合出大能力（io.ReadWriter）
type ReadWriter interface {
    Reader
    Writer
}

type Client struct { timeout time.Duration }

// 接收者名 = 类型缩写 c，不是 this/self
func (c *Client) Do(req Request) (Response, error) {
    // 用 c.timeout ...
}
func (c *Client) Close() error { // 同一类型统一叫 c
    return nil
}

// 哨兵错误：导出用 Err 前缀，首字母大写
var ErrNotFound = errors.New("not found")
var ErrClosed = errors.New("already closed")

// 包装错误用 %w 保留链路（Go 1.13+）
if err != nil {
    return fmt.Errorf("query user %d: %w", id, err)
}
// 判断用 errors.Is / errors.As
if errors.Is(err, ErrNotFound) { // 处理未找到 }

// Package user 提供了用户领域模型的存储与查询能力。
package user

// User 表示一个已注册的用户。
type User struct { /* ... */ }

// GetUser 按 ID 查询用户；不存在时返回 ErrNotFound。
func GetUser(ctx context.Context, id int64) (*User, error) {
    // ...
}

延伸阅读（本仓库）

· go-zero 基础 —— 框架整体认知
· go-zero 项目规约 —— 本仓库的目录/命名落地约定
· go-zero 类型 —— struct/tag 与代码生成
· go-zero 服务启动 —— main 到端口监听