资源命名

VEF Framework 使用资源名称来标识 API 端点。遵循一致的命名约定可以避免冲突并使 API 结构清晰。

命名模式

推荐使用三级命名空间模式：

{app}/{domain}/{entity}

层级	说明	示例
app	应用或系统标识	smp、crm、erp
domain	业务领域	sys、order、product
entity	实体名称	user、role、menu

命名示例

// System management module
api.NewResource("smp/sys/user")      // User management
api.NewResource("smp/sys/role")      // Role management
api.NewResource("smp/sys/menu")      // Menu management
api.NewResource("smp/sys/dept")      // Department management

// Order module
api.NewResource("smp/order/order")   // Order management
api.NewResource("smp/order/item")    // Order items

// Product module
api.NewResource("smp/product/product")    // Product management
api.NewResource("smp/product/category")   // Product categories
api.NewResource("smp/product/brand")      // Product brands

命名优势

1. 避免冲突

不同模块可能有相同名称的实体，使用命名空间可以避免冲突：

// Both modules have "user" entity, but different namespaces
api.NewResource("smp/sys/user")      // System users
api.NewResource("smp/customer/user") // Customer users

2. 清晰的所有权

从资源名称可以清楚地知道 API 属于哪个模块：

// Clear ownership
api.NewResource("crm/contact/contact")  // CRM module
api.NewResource("erp/inventory/stock")  // ERP module

3. 便于权限控制

可以基于命名空间进行权限控制：

// Permission tokens based on resource naming
"smp/sys/user:find_page"    // View users
"smp/sys/user:create"       // Create users
"smp/order/order:*"         // All order operations

框架保留命名空间

以下资源命名空间被框架保留，不要在自定义 API 中使用：

命名空间	说明
security/auth	认证 API（登录、登出、刷新令牌等）
sys/storage	存储 API（上传、获取预签名 URL 等）
sys/monitor	监控 API（系统概览、CPU、内存等）

警告

使用保留的命名空间会导致应用启动失败，因为框架会检测到重复的 API 定义。

// ❌ Bad: Using reserved namespace
api.NewResource("security/auth/custom")  // Will conflict with built-in auth APIs

// ✅ Good: Use custom namespace
api.NewResource("app/auth/custom")       // Custom auth-related APIs

命名规范

使用小写字母

// ✅ Good
api.NewResource("smp/sys/user")

// ❌ Bad
api.NewResource("SMP/Sys/User")

使用单数形式

// ✅ Good
api.NewResource("smp/sys/user")
api.NewResource("smp/order/order")

// ❌ Bad
api.NewResource("smp/sys/users")
api.NewResource("smp/order/orders")

使用连字符分隔多词

// ✅ Good
api.NewResource("smp/sys/user-role")
api.NewResource("smp/order/order-item")

// ❌ Bad
api.NewResource("smp/sys/userRole")
api.NewResource("smp/sys/user_role")

保持一致性

在整个项目中使用一致的命名模式：

// ✅ Good: Consistent pattern
api.NewResource("smp/sys/user")
api.NewResource("smp/sys/role")
api.NewResource("smp/sys/menu")

// ❌ Bad: Inconsistent patterns
api.NewResource("smp/sys/user")
api.NewResource("system/role")
api.NewResource("menu")

完整示例

package resources

import (
    "my-app/internal/modules/user/models"
    "my-app/internal/modules/user/payloads"
    
    "github.com/ilxqx/vef-framework-go/api"
    "github.com/ilxqx/vef-framework-go/apis"
)

// UserResource follows the {app}/{domain}/{entity} naming pattern
type UserResource struct {
    api.Resource
    apis.FindPageApi[models.User, payloads.UserSearch]
    apis.CreateApi[models.User, payloads.UserParams]
    apis.UpdateApi[models.User, payloads.UserParams]
    apis.DeleteApi[models.User]
}

func NewUserResource() api.Resource {
    return &UserResource{
        // Resource name: smp/sys/user
        // - smp: application identifier
        // - sys: system domain
        // - user: entity name
        Resource:    api.NewResource("smp/sys/user"),
        FindPageApi: apis.NewFindPageApi[models.User, payloads.UserSearch](),
        CreateApi:   apis.NewCreateApi[models.User, payloads.UserParams](),
        UpdateApi:   apis.NewUpdateApi[models.User, payloads.UserParams](),
        DeleteApi:   apis.NewDeleteApi[models.User](),
    }
}

API 调用示例

# Call user API
curl -X POST http://localhost:8080/api \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "smp/sys/user",
    "action": "find_page",
    "params": {
        "page": 1,
        "pageSize": 10
    }
  }'

下一步

• 了解 参数结构 的定义方法
• 学习 预置 API 快速构建接口
• 查看 自定义处理器 添加自定义逻辑