单端点设计

VEF Framework 采用单端点设计模式，所有 API 请求都通过统一的入口点进行处理。这种设计简化了路由管理，提供了一致的请求响应格式。

设计理念

传统的 RESTful API 为每个资源和操作定义独立的端点：

GET    /api/users
POST   /api/users
GET    /api/users/:id
PUT    /api/users/:id
DELETE /api/users/:id

VEF Framework 采用不同的方式，所有请求都通过单一端点：

POST /api        # Internal API endpoint
POST /openapi    # External API endpoint (for third-party integrations)

请求格式

所有 API 请求使用统一的 JSON 格式：

{
    "resource": "app/sys/user",
    "action": "find_page",
    "params": {
        "page": 1,
        "pageSize": 10,
        "username": "john"
    },
    "meta": {
        "requestId": "req-123456"
    }
}

请求字段说明

字段	类型	必填	说明
resource	string	是	资源标识符，格式为 {app}/{domain}/{entity}
action	string	是	操作名称，如 find_all、create、update 等
params	object	否	请求参数，根据不同操作传递不同参数
meta	object	否	元数据，用于传递请求 ID、追踪信息等

Params vs Meta

• params: 业务参数，直接影响 API 的执行逻辑
• meta: 元数据，用于日志、追踪、审计等非业务目的

// Example: params contains business data
// meta contains tracking information
{
    "resource": "app/order/order",
    "action": "create",
    "params": {
        "customerId": "cust-001",
        "items": [
            {"productId": "prod-001", "quantity": 2}
        ]
    },
    "meta": {
        "requestId": "req-789",
        "traceId": "trace-abc",
        "clientVersion": "1.0.0"
    }
}

响应格式

所有 API 响应也使用统一的 JSON 格式：

成功响应

{
    "success": true,
    "data": {
        "id": "user-001",
        "username": "john",
        "email": "john@example.com"
    }
}

分页响应

{
    "success": true,
    "data": {
        "items": [
            {"id": "user-001", "username": "john"},
            {"id": "user-002", "username": "jane"}
        ],
        "total": 100,
        "page": 1,
        "pageSize": 10
    }
}

错误响应

{
    "success": false,
    "message": "User not found",
    "code": "USER_NOT_FOUND"
}

响应字段说明

字段	类型	说明
success	boolean	请求是否成功
data	any	成功时返回的数据
message	string	错误消息（失败时）
code	string	错误代码（失败时）

预置操作

VEF Framework 提供了一组预置的操作名称：

操作	说明
find_one	查询单条记录
find_all	查询所有记录
find_page	分页查询
find_tree	树形结构查询
find_options	选项列表查询
find_tree_options	树形选项查询
create	创建记录
update	更新记录
delete	删除记录
create_many	批量创建
update_many	批量更新
delete_many	批量删除
import	导入数据
export	导出数据

代码示例

定义资源

package resources

import (
    "github.com/ilxqx/vef-framework-go/api"
    "github.com/ilxqx/vef-framework-go/apis"
)

// UserResource defines the user API resource
// The resource name "app/sys/user" determines the API endpoint
type UserResource struct {
    api.Resource
    apis.FindPageApi[models.User, payloads.UserSearch]
    apis.CreateApi[models.User, payloads.UserParams]
}

func NewUserResource() api.Resource {
    return &UserResource{
        // Resource name follows {app}/{domain}/{entity} pattern
        Resource:    api.NewResource("app/sys/user"),
        FindPageApi: apis.NewFindPageApi[models.User, payloads.UserSearch](),
        CreateApi:   apis.NewCreateApi[models.User, payloads.UserParams](),
    }
}

调用 API

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

# Create a new user
curl -X POST http://localhost:8080/api \
  -H "Content-Type: application/json" \
  -d '{
    "resource": "app/sys/user",
    "action": "create",
    "params": {
        "username": "newuser",
        "email": "newuser@example.com"
    }
  }'

优势

1. 简化路由管理

不需要为每个资源定义多个路由，所有请求通过统一入口处理。

2. 一致的接口规范

所有 API 遵循相同的请求响应格式，降低学习成本。

3. 便于权限控制

基于 resource 和 action 的组合进行权限验证，逻辑清晰。

4. 易于监控和日志

统一的入口点便于添加中间件进行日志记录、性能监控等。

5. 支持批量操作

可以在单个请求中执行多个操作（通过自定义处理器实现）。

OpenAPI 端点

对于外部集成，VEF Framework 提供了 /openapi 端点，支持 OpenAPI 签名认证：

# External API call with signature
curl -X POST http://localhost:8080/openapi \
  -H "Content-Type: application/json" \
  -H "X-App-Key: your-app-key" \
  -H "X-Signature: calculated-signature" \
  -H "X-Timestamp: 1234567890" \
  -d '{
    "resource": "app/sys/user",
    "action": "find_all"
  }'

下一步

• 了解 依赖注入 机制
• 学习 模块化架构 组织代码
• 查看 预置 API 快速构建接口