GoTrain 项目开发指南项目架构

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

手动复制操作：

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 注解说明：

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) }

文件命名规范

依赖注入规范

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

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() }

说明：

使用示例：

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文件中。