快速开始

本指南将帮助你快速了解 VEF Framework Go 并创建你的第一个应用。

环境要求

在开始之前，请确保你的开发环境满足以下要求：

• Go 版本: 1.25.0 或更高版本
• 操作系统: Linux、macOS 或 Windows
• 数据库: PostgreSQL、MySQL 或 SQLite（可选）

安装

创建新项目

# Create a new directory for your project
mkdir my-vef-app
cd my-vef-app

# Initialize Go module
go mod init my-vef-app

安装 VEF Framework

# Install VEF Framework Go
go get github.com/ilxqx/vef-framework-go

提示

如果在执行 go mod tidy 时遇到 google.golang.org/genproto 的歧义导入错误，请运行：

go get google.golang.org/genproto/googleapis/api@latest
go get google.golang.org/genproto/googleapis/rpc@latest

最小化示例

创建 main.go 文件：

package main

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

func main() {
    // Start the VEF application
    // This will automatically load configuration and start the HTTP server
    vef.Run()
}

创建配置文件 configs/application.toml：

[vef]
# Application name
name = "my-vef-app"

[vef.server]
# Server port
port = 8080

[vef.database]
# Database driver: postgres, mysql, sqlite
driver = "sqlite"
# Database connection string
dsn = "file:app.db?cache=shared&mode=rwc"

运行应用

# Run the application
go run main.go

你的 API 服务器现在运行在 http://localhost:8080。

测试 API

VEF Framework 使用单端点设计，所有 API 请求都通过 POST /api 发送：

# Test the API endpoint
curl -X POST http://localhost:8080/api \
  -H "Content-Type: application/json" \
  -d '{"resource": "health", "action": "check"}'

项目结构

推荐的项目目录组织方式：

my-vef-app/
├── cmd/
│   └── main.go              # Application entry point
├── configs/
│   └── application.toml     # Configuration file
├── internal/
│   ├── modules/             # Business modules
│   │   └── user/            # User module example
│   │       ├── module.go    # Module definition
│   │       ├── models/      # Data models
│   │       ├── payloads/    # Request/response payloads
│   │       ├── resources/   # API resources
│   │       └── services/    # Business services
│   └── app.go               # Application setup
├── go.mod
└── go.sum

目录说明

目录	说明
cmd/	应用程序入口点
configs/	配置文件
internal/modules/	业务模块，按领域组织
models/	数据库模型定义
payloads/	请求参数和响应结构
resources/	API 资源定义
services/	业务逻辑服务

创建第一个 API

让我们创建一个简单的用户管理 API：

1. 定义模型

// internal/modules/user/models/user.go
package models

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

// User represents a user in the system
type User struct {
    orm.Model
    Username string `bun:"username,notnull" json:"username"`
    Email    string `bun:"email,notnull" json:"email"`
    IsActive bool   `bun:"is_active,notnull,default:true" json:"isActive"`
}

2. 定义参数结构

// internal/modules/user/payloads/user.go
package payloads

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

// UserSearch defines search parameters for user queries
type UserSearch struct {
    api.P
    Username string `json:"username" search:"contains"`
    Email    string `json:"email" search:"contains"`
}

// UserParams defines parameters for creating/updating users
type UserParams struct {
    api.P
    Username string `json:"username" validate:"required,max=32"`
    Email    string `json:"email" validate:"required,email"`
    IsActive bool   `json:"isActive"`
}

3. 创建资源

// internal/modules/user/resources/user.go
package resources

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

// UserResource defines the user API resource
type UserResource struct {
    api.Resource
    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]
}

// NewUserResource creates a new user resource
func NewUserResource() api.Resource {
    return &UserResource{
        Resource:    api.NewResource("app/sys/user"),
        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](),
    }
}

4. 注册模块

// internal/modules/user/module.go
package user

import (
    "my-vef-app/internal/modules/user/resources"
    
    "github.com/ilxqx/vef-framework-go/vef"
)

// Module returns the user module
func Module() vef.ModuleFunc {
    return vef.Module(
        vef.ProvideResource(resources.NewUserResource),
    )
}

5. 启动应用

// cmd/main.go
package main

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

func main() {
    vef.Run(
        user.Module(),
    )
}

故障排查

常见问题

1. 依赖安装失败

如果遇到依赖安装问题，尝试清理模块缓存：

go clean -modcache
go mod tidy

2. 端口被占用

如果端口 8080 被占用，可以在配置文件中修改端口：

[vef.server]
port = 3000

3. 数据库连接失败

检查数据库配置是否正确：

[vef.database]
driver = "postgres"
dsn = "postgres://user:password@localhost:5432/dbname?sslmode=disable"

4. 模块未加载

确保模块已在 main.go 中注册：

vef.Run(
    user.Module(),  // Make sure this is included
)

下一步

• 了解 单端点设计 架构模式
• 学习 依赖注入 的使用方法
• 探索 预置 API 快速构建 CRUD 接口
• 查看 最佳实践 组织项目结构