预置 API

VEF Framework 提供了一组预置的 API 类型，用于快速构建标准的 CRUD 接口。

可用的预置 API

API 类型	操作名称	说明
FindOneApi	find_one	查询单条记录
FindAllApi	find_all	查询所有记录
FindPageApi	find_page	分页查询
FindTreeApi	find_tree	树形结构查询
FindOptionsApi	find_options	选项列表查询
FindTreeOptionsApi	find_tree_options	树形选项查询
CreateApi	create	创建单条记录
UpdateApi	update	更新单条记录
DeleteApi	delete	删除单条记录
CreateManyApi	create_many	批量创建
UpdateManyApi	update_many	批量更新
DeleteManyApi	delete_many	批量删除
ImportApi	import	从 Excel/CSV 导入
ExportApi	export	导出到 Excel/CSV

基本用法

定义资源

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 with common CRUD APIs
type UserResource struct {
    api.Resource
    apis.FindOneApi[models.User, payloads.UserSearch]
    apis.FindAllApi[models.User, payloads.UserSearch]
    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:    api.NewResource("smp/sys/user"),
        FindOneApi:  apis.NewFindOneApi[models.User, payloads.UserSearch](),
        FindAllApi:  apis.NewFindAllApi[models.User, payloads.UserSearch](),
        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

FindOneApi

查询单条记录：

// Definition
apis.FindOneApi[models.User, payloads.UserSearch]

// Request
{
    "resource": "smp/sys/user",
    "action": "find_one",
    "params": {
        "id": "user-001"
    }
}

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

FindAllApi

查询所有记录（无分页）：

// Definition
apis.FindAllApi[models.User, payloads.UserSearch]

// Request
{
    "resource": "smp/sys/user",
    "action": "find_all",
    "params": {
        "isActive": true
    }
}

// Response
{
    "success": true,
    "data": [
        {"id": "user-001", "username": "john"},
        {"id": "user-002", "username": "jane"}
    ]
}

FindPageApi

分页查询：

// Definition
apis.FindPageApi[models.User, payloads.UserSearch]

// Request
{
    "resource": "smp/sys/user",
    "action": "find_page",
    "params": {
        "page": 1,
        "pageSize": 10,
        "username": "john"
    }
}

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

FindTreeApi

树形结构查询：

import "github.com/ilxqx/vef-framework-go/treebuilder"

// Definition with tree builder function
apis.FindTreeApi[models.Department, payloads.DeptSearch]

// Constructor
FindTreeApi: apis.NewFindTreeApi[models.Department, payloads.DeptSearch](
    buildDepartmentTree,
).
    WithIdColumn("id").
    WithParentIdColumn("parent_id"),

// Tree builder function
func buildDepartmentTree(items []models.Department) []models.Department {
    return treebuilder.Build(
        items,
        treebuilder.Adapter[models.Department]{
            GetId:       func(m models.Department) string { return m.Id },
            GetParentId: func(m models.Department) string { return m.ParentId.ValueOrZero() },
            SetChildren: func(m *models.Department, children []models.Department) {
                m.Children = children
            },
        },
    )
}

// Response
{
    "success": true,
    "data": [
        {
            "id": "dept-001",
            "name": "Engineering",
            "children": [
                {"id": "dept-002", "name": "Frontend", "children": []},
                {"id": "dept-003", "name": "Backend", "children": []}
            ]
        }
    ]
}

FindOptionsApi

选项列表查询（用于下拉框）：

// Definition
apis.FindOptionsApi[models.User, payloads.UserSearch]

// Constructor with column mapping
FindOptionsApi: apis.NewFindOptionsApi[models.User, payloads.UserSearch]().
    WithDefaultColumnMapping(&apis.DataOptionColumnMapping{
        LabelColumn: "username",
        ValueColumn: "id",
    }),

// Response
{
    "success": true,
    "data": [
        {"label": "john", "value": "user-001"},
        {"label": "jane", "value": "user-002"}
    ]
}

写入 API

CreateApi

创建单条记录：

// Definition
apis.CreateApi[models.User, payloads.UserParams]

// Request
{
    "resource": "smp/sys/user",
    "action": "create",
    "params": {
        "username": "newuser",
        "email": "newuser@example.com",
        "password": "secret123"
    }
}

// Response
{
    "success": true,
    "data": {
        "id": "user-003",
        "username": "newuser",
        "email": "newuser@example.com"
    }
}

UpdateApi

更新单条记录：

// Definition
apis.UpdateApi[models.User, payloads.UserParams]

// Request
{
    "resource": "smp/sys/user",
    "action": "update",
    "params": {
        "id": "user-001",
        "email": "john.new@example.com"
    }
}

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

DeleteApi

删除单条记录：

// Definition
apis.DeleteApi[models.User]

// Request
{
    "resource": "smp/sys/user",
    "action": "delete",
    "params": {
        "id": "user-001"
    }
}

// Response
{
    "success": true
}

批量操作 API

CreateManyApi

批量创建：

// Definition
apis.CreateManyApi[models.User, payloads.UserParams]

// Request
{
    "resource": "smp/sys/user",
    "action": "create_many",
    "params": {
        "items": [
            {"username": "user1", "email": "user1@example.com"},
            {"username": "user2", "email": "user2@example.com"}
        ]
    }
}

UpdateManyApi

批量更新：

// Definition
apis.UpdateManyApi[models.User, payloads.UserParams]

// Request
{
    "resource": "smp/sys/user",
    "action": "update_many",
    "params": {
        "items": [
            {"id": "user-001", "isActive": false},
            {"id": "user-002", "isActive": false}
        ]
    }
}

DeleteManyApi

批量删除：

// Definition
apis.DeleteManyApi[models.User]

// Request
{
    "resource": "smp/sys/user",
    "action": "delete_many",
    "params": {
        "ids": ["user-001", "user-002"]
    }
}

导入导出 API

ImportApi

从 Excel/CSV 导入：

// Definition
apis.ImportApi[models.User, payloads.UserParams]

// Request (multipart/form-data)
// file: users.xlsx

ExportApi

导出到 Excel/CSV：

// Definition
apis.ExportApi[models.User, payloads.UserSearch]

// Constructor with options
ExportApi: apis.NewExportApi[models.User, payloads.UserSearch]().
    WithDefaultFormat("excel").
    WithFilenameBuilder(func(search payloads.UserSearch, ctx fiber.Ctx) string {
        return fmt.Sprintf("users_%s", time.Now().Format("20060102"))
    }),

// Request
{
    "resource": "smp/sys/user",
    "action": "export",
    "params": {
        "isActive": true
    }
}

完整资源示例

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 with all CRUD APIs
type UserResource struct {
    api.Resource
    
    // Query APIs
    apis.FindOneApi[models.User, payloads.UserSearch]
    apis.FindAllApi[models.User, payloads.UserSearch]
    apis.FindPageApi[models.User, payloads.UserSearch]
    apis.FindOptionsApi[models.User, payloads.UserSearch]
    
    // Write APIs
    apis.CreateApi[models.User, payloads.UserCreateParams]
    apis.UpdateApi[models.User, payloads.UserUpdateParams]
    apis.DeleteApi[models.User]
    
    // Batch APIs
    apis.CreateManyApi[models.User, payloads.UserCreateParams]
    apis.DeleteManyApi[models.User]
    
    // Import/Export APIs
    apis.ImportApi[models.User, payloads.UserCreateParams]
    apis.ExportApi[models.User, payloads.UserSearch]
}

func NewUserResource() api.Resource {
    return &UserResource{
        Resource: api.NewResource("smp/sys/user"),
        
        // Query APIs
        FindOneApi:     apis.NewFindOneApi[models.User, payloads.UserSearch](),
        FindAllApi:     apis.NewFindAllApi[models.User, payloads.UserSearch](),
        FindPageApi:    apis.NewFindPageApi[models.User, payloads.UserSearch](),
        FindOptionsApi: apis.NewFindOptionsApi[models.User, payloads.UserSearch]().
            WithDefaultColumnMapping(&apis.DataOptionColumnMapping{
                LabelColumn: "username",
                ValueColumn: "id",
            }),
        
        // Write APIs
        CreateApi: apis.NewCreateApi[models.User, payloads.UserCreateParams](),
        UpdateApi: apis.NewUpdateApi[models.User, payloads.UserUpdateParams](),
        DeleteApi: apis.NewDeleteApi[models.User](),
        
        // Batch APIs
        CreateManyApi: apis.NewCreateManyApi[models.User, payloads.UserCreateParams](),
        DeleteManyApi: apis.NewDeleteManyApi[models.User](),
        
        // Import/Export APIs
        ImportApi: apis.NewImportApi[models.User, payloads.UserCreateParams](),
        ExportApi: apis.NewExportApi[models.User, payloads.UserSearch](),
    }
}

下一步

• 了解 构建器方法 配置 API 行为
• 学习 FindApi 配置 的高级选项
• 查看 钩子 添加业务逻辑