命名约定

VEF Framework 项目的命名规范和最佳实践。

文件命名

Go 文件

user.go              # 模型文件
user_resource.go     # 资源文件
user_service.go      # 服务文件
user_test.go         # 测试文件

配置文件

config.yaml          # 默认配置
config.dev.yaml      # 开发环境
config.prod.yaml     # 生产环境

包命名

// Good
package models
package resources
package services
package payloads

// Bad
package Models
package userModels
package user_models

类型命名

模型

// Good
type User struct {}
type UserRole struct {}
type OrderItem struct {}

// Bad
type user struct {}        // Not exported
type TUser struct {}       // Unnecessary prefix
type UserModel struct {}   // Redundant suffix

资源

// Good
type UserResource struct {}
type OrderResource struct {}

// Bad
type UserRes struct {}     // Unclear abbreviation
type UsersResource struct {} // Plural

参数结构

// Good
type UserSearch struct {}      // Search parameters
type UserCreateParams struct {} // Create parameters
type UserUpdateParams struct {} // Update parameters

// Bad
type UserSearchDTO struct {}   // Unnecessary suffix
type SearchUser struct {}      // Verb first

函数命名

构造函数

// Good
func NewUserResource() api.Resource
func NewUserService(db *gorm.DB) *UserService

// Bad
func CreateUserResource() api.Resource  // Use New prefix
func UserResourceNew() api.Resource     // Wrong order

方法

// Good
func (r *UserResource) GetProfile(ctx fiber.Ctx) error
func (s *UserService) FindByEmail(email string) (*User, error)

// Bad
func (r *UserResource) Profile(ctx fiber.Ctx) error  // Missing verb
func (s *UserService) GetUserByEmail(email string)   // Redundant "User"

变量命名

局部变量

// Good
user := &models.User{}
users := []models.User{}
userCount := len(users)
isActive := true

// Bad
u := &models.User{}      // Too short
theUser := &models.User{} // Unnecessary prefix
user_count := len(users)  // Snake case

常量

// Good
const (
    MaxPageSize     = 100
    DefaultPageSize = 20
    TokenExpiration = 24 * time.Hour
)

// Bad
const (
    MAX_PAGE_SIZE = 100  // Use camelCase
    maxpagesize   = 100  // Not exported, hard to read
)

资源命名

API 资源路径

// Good - {app}/{domain}/{entity}
api.NewResource("smp/sys/user")
api.NewResource("smp/order/order")
api.NewResource("smp/product/category")

// Bad
api.NewResource("user")           // Missing app and domain
api.NewResource("smp/users")      // Plural
api.NewResource("SMP/Sys/User")   // Wrong case

操作命名

// Good - snake_case for actions
"find_one"
"find_page"
"create"
"update"
"delete"
"reset_password"

// Bad
"findOne"        // camelCase
"FindPage"       // PascalCase
"resetpassword"  // No separator

数据库命名

表名

-- Good - snake_case, plural
users
user_roles
order_items

-- Bad
User           -- PascalCase
userRoles      -- camelCase
user_role      -- Singular for junction table

列名

-- Good - snake_case
id
username
created_at
department_id

-- Bad
Id             -- PascalCase
createdAt      -- camelCase
DepartmentID   -- Mixed case

JSON 命名

请求/响应字段

type User struct {
    Id        string `json:"id"`
    Username  string `json:"username"`
    Email     string `json:"email"`
    IsActive  bool   `json:"isActive"`    // camelCase
    CreatedAt string `json:"createdAt"`
}

完整示例

// internal/modules/order/models/order.go
package models

import (
    "github.com/ilxqx/vef-framework-go/orm"
    "github.com/ilxqx/vef-framework-go/null"
)

// Order represents an order in the system
type Order struct {
    orm.Model
    OrderNo      string      `gorm:"size:50;uniqueIndex;not null" json:"orderNo"`
    UserId       string      `gorm:"size:36;index;not null" json:"userId"`
    TotalAmount  float64     `gorm:"type:decimal(10,2);not null" json:"totalAmount"`
    Status       string      `gorm:"size:20;default:'pending'" json:"status"`
    Remark       null.String `gorm:"size:500" json:"remark"`
    
    // Relations
    User  *User       `gorm:"foreignKey:UserId" json:"user,omitempty"`
    Items []OrderItem `gorm:"foreignKey:OrderId" json:"items,omitempty"`
}

// TableName returns the table name
func (Order) TableName() string {
    return "orders"
}

下一步

• 了解 项目结构 组织代码文件
• 学习 定义模型 模型命名规范
• 查看 字段标签 标签命名规范