GoTrain 项目开发指南

1 make code table=users
2 cd ./goapi/data/code/internal/dbentity
3 copy entity ,dao至beapi dbdao dbentity
4 ai生成uiTableRequest
对于公共代码可以开发
apiservice
apifacade
domainfacade
5 ai生成TableController
6 编写swag
7 测试
8 make doc生成文档
9 make dev安装

GoTrain项目开发指南摘要：本项目采用分层架构设计，包含API核心模块和Web控制器模块。开发流程包括：1)使用makecode命令生成实体代码；2)迁移代码至正式目录；3)生成UI请求对象；4)创建Controller；5)编写Swagger文档；6)单元测试；7)生成API文档；8)安装运行。项目遵循标准化规范，提供代码生成模板和依赖注入机制，支持分页查询、排序、导出等通用功能。通过分层设计（DAO层、API服务层、控制器层）实现业务逻辑解耦，提高开发效率和代码可维护性。

项目架构概述

本项目采用分层架构设计，遵循 Clean Architecture 原则，整体结构如下：

plainText

├── beapi/                    # API 核心模块
│   ├── data/code/internal/dbentity/   # 代码生成临时目录
│   ├── db/                   # 数据访问层
│   │   ├── dbdao/            # DAO 层（数据访问对象）
│   │   ├── dbentity/         # 数据库实体
│   │   ├── apiservice/       # API 服务层
│   │   └── apiface/          # API 接口定义
│   ├── trainframe/           # 业务框架
│   │   ├── service/          # 业务服务层
│   │   └── repository/       # 数据仓库层
│   └── webframe/             # Web 框架基础设施
└── beweb/                    # Web 控制器模块
    └── webctl/               # REST API 控制器

---

开发流程指南

1. 代码生成：根据数据库表生成实体代码

命令执行：

bash

make code table=users

作用： 根据数据库表结构自动生成实体类和基础 DAO 代码，输出到 beapi/data/code/internal/dbentity/ 目录。

生成文件示例：

• users.go - 实体类定义（包含字段映射、表名、主键等）
• users_dao.go - DAO 数据访问对象
• users_init.go - 依赖注入初始化文件

实体类结构示例：

go

type Users struct {
    basedto.BaseEntity
    Id        int64     `json:"id,string" gorm:"primaryKey"`
    Name      string    `json:"name" gorm:"column:name"`
    Phone     string    `json:"phone" gorm:"column:phone"`
    CreatedAt time.Time `json:"created_at" gorm:"column:created_at"`
}

func (u *Users) TableName() string {
    return "users"
}

func (u *Users) PkeyName() string {
    return "id"
}

---

2. 代码迁移：复制生成的代码到正式目录

命令执行：

bash

cd ./beapi/data/code/internal/dbentity

手动复制操作：

源文件	目标目录	说明
users.go	beapi/db/dbentity/userentity/	实体类
users_dao.go	beapi/db/dbdao/userdao/	DAO 层
users_init.go	beapi/db/dbentity/userentity/	初始化文件
users_dao_init.go	beapi/db/dbdao/userdao/	DAO 初始化文件

---

3. 生成 UI 请求对象：ai生成uiTableRequest

设计原则：

• 请求对象用于接收前端查询参数
• 继承基础分页查询结构
• 支持关键字搜索、字段过滤、排序等

示例结构：

go

type UiUsersRequest struct {
    basedto.BaseEntity
    Name       string `json:"name"`       // 用户姓名
    Phone      string `json:"phone"`      // 手机号
    UserType   int32  `json:"userType"`   // 用户类型
    PageNum    int    `json:"pageNum"`    // 页码
    PageSize   int    `json:"pageSize"`   // 每页数量
    OrderBy    string `json:"orderBy"`    // 排序字段
    SortBy     string `json:"sortBy"`     // 排序方向(asc/desc)
}

创建位置： beweb/uipage/uitrain/ui_users_request.go

---

4. 生成 Controller：ai生成TableController

Controller 设计规范：

go

type UsersController struct {
    userService serviceuser.UserService
    ctlbase.BaseController
    basedto.BaseEntitySingle
}

func DefaultUsersController() webfacade.Controller {
    return &UsersController{
        userService: serviceuser.FindBeanuserService(),
    }
}

// RegisterRoute 注册路由
func (c *UsersController) RegisterRoute(api *gin.RouterGroup) {
    api.GET("/users", c.List)
    api.GET("/users/:id", c.Get)
    api.POST("/users", c.Create)
    api.PUT("/users/:id", c.Update)
    api.DELETE("/users/:id", c.Delete)
}

创建位置： beweb/webctl/ctluser/users_controller.go

---

5. 编写 Swagger 文档注释

Swagger 注解规范：

go

// @Summary 获取用户列表
// @Description 根据条件分页查询用户列表
// @Produce json
// @Tags 用户管理
// @Security JWT
// @Param name query string false "用户姓名"
// @Param phone query string false "手机号"
// @Param pageNum query int false "页码" default(1)
// @Param pageSize query int false "每页数量" default(20)
// @Success 200 {object} common.Response{data=common.PaginationResult{list=[]entityuser.Users}}
// @Router /api/v1/users [get]
func (c *UsersController) List(ctx *gin.Context) {
    // ...
}

Swagger 注解说明：

注解	说明	示例
@Summary	接口摘要	获取用户列表
@Description	接口描述	详细说明
@Produce	响应格式	json
@Tags	分组标签	用户管理
@Security	安全认证	JWT
@Param	请求参数	name query string
@Success	成功响应	200 {object} Response
@Router	路由路径	/api/v1/users [get]

---

6. 测试

单元测试规范：

go

func TestUsersController_List(t *testing.T) {
    ctrl := DefaultUsersController()
    req := &apimodel.QueryUserRequest{
        ObjectId: "test",
    }
    
    result := ctrl.userService.QueryUsers(req)
    assert.NotNil(t, result)
    assert.True(t, result.Success)
}

测试命令：

bash

go test -v ./beweb/webctl/ctluser/... -run TestUsersController

---

7. 生成 API 文档

命令执行：

bash

make doc

作用： 使用 Swaggo 生成 OpenAPI 文档

生成产物：

• trainplat/server/docs/docs.go - Swagger 文档定义
• 访问地址：http://localhost:8080/swagger/index.html

---

8. 开发环境安装

命令执行：

bash

make dev

作用：

• 安装所有依赖包
• 编译项目
• 启动开发服务器

启动命令：

bash

go run trainplat/server/main.go

服务访问：

• API 地址：http://localhost:8080/api/v1/
• Swagger 文档：http://localhost:8080/swagger/index.html

---

公共代码开发建议

apiservice - API 服务层

用于封装复杂业务逻辑，作为 Controller 和 Repository 之间的桥梁。

go

type UserApiService struct {
    basedto.BaseEntitySingle
    userRepository reposuser.UserRepository
}

func (s *UserApiService) GetUserInfo(userId int64) (*userentity.Users, error) {
    // 组合多个 Repository 操作
    user, err := s.userRepository.FindById(userId)
    if err != nil {
        return nil, err
    }
    // 添加额外业务逻辑
    return user, nil
}

apifacade - API 门面层

提供统一的 API 入口，聚合多个服务。

go

type ApiFacade struct {
    userService    serviceuser.UserService
    creditService  servicecredit.CreditService
    planService    serviceplan.PlanService
}

func (f *ApiFacade) CreateUser(ctx context.Context, user *entityuser.User) (*entityuser.User, error) {
    // 事务处理
    // 调用多个服务
    return user, nil
}

domainfacade - 领域门面层

封装领域业务规则，供多个模块复用。

go

type DomainFacade struct {
    basedto.BaseEntitySingle
}

func (f *DomainFacade) ValidateUserRole(user *entityuser.User, role string) bool {
    // 领域规则验证
    return strings.Contains(user.RelRole, role)
}

---

文件命名规范

类型	命名规则	示例
实体类	首字母大写单数	Users, Student
DAO	实体名 + Dao	UsersDao
Service	实体名 + Service	UserService
Controller	实体名 + Controller	UsersController
请求DTO	Ui + 实体名 + Request	UiUsersRequest
响应DTO	实体名 + Result	UsersResult

---

依赖注入规范

所有服务需提供初始化函数：

go

// 用户服务初始化
func init() {
    godi.RegisterBean("UserService", NewUserService)
}

func FindBeanUserService() *UserService {
    return godi.FindBean[*UserService]("UserService")
}

---

代码提交规范

bash

# 提交格式
git commit -m "feat: 添加用户查询接口"
git commit -m "fix: 修复用户创建失败问题"
git commit -m "docs: 更新API文档"
git commit -m "refactor: 重构用户服务"

---

总结

本项目采用标准化的代码生成和开发流程，核心步骤为：

1. 代码生成 → make code table=xxx
2. 代码迁移 → 复制到正式目录
3. 生成请求对象 → UiXXXRequest
4. 生成控制器 → XXXController
5. 编写文档 → Swagger 注解
6. 测试验证 → 单元测试
7. 生成文档 → make doc
8. 部署运行 → make dev

通过遵循以上规范，可以高效、规范地完成业务功能开发。

根据查看的代码结构，我需要创建一个继承 uiframe.UiSimpleRequest 的 UiUsersRequest。

go

package uiframe

import (
	"gitea.super-study.com/ys-study/gotrain/beapi/db/dbentity/userentity"
)

// UiUsersRequest 用户列表查询请求
// 继承 UiSimpleRequest，支持通用的分页、排序、搜索功能
type UiUsersRequest struct {
	*UiSimpleRequest[int64, *userentity.Users]
}

// NewUiUsersRequest 创建用户查询请求实例
func NewUiUsersRequest() *UiUsersRequest {
	return &UiUsersRequest{
		UiSimpleRequest: NewUiSimpleRequest[int64, *userentity.Users](),
	}
}

// BuildQuery 构建查询条件
func (self *UiUsersRequest) BuildQuery() *UiUsersRequest {
	self.UiSimpleRequest.BuildRequest()
	return self
}

// List 执行查询并返回结果
func (self *UiUsersRequest) List() *PageResult[*userentity.Users] {
	return self.UiSimpleRequest.List()
}

说明：

方法	功能说明
NewUiUsersRequest()	创建查询请求实例，自动初始化 DAO 和参数
BuildQuery()	构建查询条件（分页、排序等）
List()	执行查询，返回分页结果
继承自 UiSimpleRequest	支持排序、分页、搜索、导出等通用功能

使用示例：

go

// 创建查询请求
req := NewUiUsersRequest()

// 设置查询条件
req.DbEq("user_type", 20)  // 查询学员
req.DbLike("name", "张")    // 姓名包含"张"
req.OrderByDesc("created_at")

// 执行查询
result := req.List()

// 导出Excel
req.ExportDefault(ctx)

继承的通用功能：

• 分页查询（PageSize, PageCurrent）
• 排序支持（OrderBys）
• 关键字搜索（Keyword）
• Excel/PDF/HTML 导出
• 数据权限过滤（DataScopeFilter）

请将此代码保存到 beapi/gotool/dbframe/uiframe/ui_users_request.go 文件中。