goweb3系列解析17：webexample

webexample 模块解析webexample是 goweb3 项目中Web 开发的完整示例模块展示了如何基于 goweb3 框架快速构建 RESTful API。一、模块架构plainTextwebexample/ ├── user_contact.go # 实体模型Model ├── user_contact_init.go # 实体依赖注入注册 ├── ui_user_contact.go # UI 请求封装Request ├── ui_user_contact_init.go # UI 请求依赖注入注册 ├── user_contact_ctl.go # 控制器Controller ├── user_contact_ctl_init.go # 控制器依赖注入注册 └── webexample_test.go # 测试用例二、核心组件详解1. UserContact - 实体模型gotype UserContact struct { basedto.BaseEntity json:- gorm:- simplemodel.Model // 继承基础模型包含 id, created_at, updated_at, deleted_at UserType int json:- // 用户类型 UserId int64 json:userId,string // 用户ID FeishuWebHook string json:feishuWebHook // 飞书WebHook FeishuId string json:feishuId // 飞书ID WeixinQrUrl string json:weixinQrUrl // 微信二维码URL }必须实现的接口方法说明PkeyName()返回主键字段名PkeyValue()返回主键值TableName()返回表名NewDao()创建 DAO 实例缓存支持gofunc (self *UserContact) ObjectKey() string { var keys []any{ ichubconfig.FindEnv(), db, self.TableName(), self.PkeyValue(), } return strings.Join(gconv.SliceStr(keys), :) // 格式: env:db:user_contact:id }2. UiUserContact - UI 请求封装gotype UiUserContact struct { basedto2.BaseEntity uiframe.UiSimpleQ[*UserContactReq, *UserContact] // 泛型 UI 查询 } type UserContactReq struct { UserId int64 json:userId,string Id int64 json:id,string }查询条件构建gofunc (self *UiUserContact) initQuery() *UiUserContact { self.SetBeforeQuery(func() { self.BuildGeneralParams(self.PageDb) if self.Query.Id 0 { self.DbEq(id, self.Query.Id) } if self.Query.UserId 0 { self.DbEq(user_id, self.Query.UserId) } if self.Query.Id 0 self.Query.UserId 0 { self.DbWhere(id ? or user_id ?, self.Query.Id, self.Query.UserId) } }) return self }核心方法方法说明UiList()分页查询列表List()内部查询方法UiSave2Result()保存新增/更新UiUpdate2Result()更新3. UserContactCtl - 控制器gotype UserContactCtl struct { funchandler.FuncService // 继承通用服务 basedto.BaseEntitySingle // 单例基类 } func (self *UserContactCtl) RegisterRoute(api *gin.RouterGroup) { api.POST(/example/user/contact/uilist, self.UiList) api.GET(/example/user/contact/uilist, self.UiList) api.POST(/example/user/contact/uisave, self.UiSave2Result) api.PUT(/example/user/contact/uiupdate, self.UiUpdate2Result) api.GET(/example/user/contact/findById/:id, self.FindById) api.DELETE(/example/user/contact/deleteById/:id, self.DeleteById) }API 路由表HTTP 方法路径方法说明POST/GET/example/user/contact/uilistUiList查询列表POST/GET/example/user/contact/uisaveUiSave2Result保存新增PUT/POST/example/user/contact/uiupdateUiUpdate2Result更新GET/example/user/contact/findById/:idFindById根据ID查询DELETE/POST/example/user/contact/deleteById/:idDeleteById删除三、数据流转流程plainText┌─────────────────────────────────────────────────────────────────┐ │ webexample 数据流程 │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ HTTP 请求 │ │ │ │ │ ▼ │ │ UserContactCtl.UiList(c) │ │ │ │ │ │ 1. ParseBody(c, req) - 解析请求体 │ │ │ 2. req.UiList() - 调用业务方法 │ │ ▼ │ │ UiUserContact.UiList() │ │ │ │ │ │ 1. List() - 构建查询 │ │ │ 2. BuildRequestQuery() - 应用查询条件 │ │ │ 3. QueryModel() - 执行数据库查询 │ │ ▼ │ │ generaldao.BaseDao.QueryModel() │ │ │ │ │ │ 1. 构建 WHERE 条件 │ │ │ 2. 执行 SQL 查询 │ │ │ 3. 返回 PageResult │ │ ▼ │ │ pagemodel.PageResult │ │ │ │ │ ▼ │ │ HTTP 响应 │ │ │ └─────────────────────────────────────────────────────────────────┘四、依赖关系plainTextwebexample ├── goconfig/base/basedto # 基础 DTO ├── goconfig/ichubconfig # 配置管理 ├── goconfig/ichublog/golog # 日志 ├── gotool/dbframe/uiframe # UI 查询框架 ├── goweb/generaldb/generaldao # 通用 DAO ├── goweb/pagemodel # 分页模型 ├── goweb/webserver/funchandler # 处理器基类 ├── gin-gonic/gin # Web 框架 └── gomini/minitest/testgin # 测试框架五、测试用例gofunc (self *TestWebExampleSuite) Test001_UiTrialTransList() { var url /api/v1/example/user/contact/UiList var testframe testgin.FindBeanGinTestframe().InitPost(url, FindBeanUserContactCtl().UiList) var req FindBeanUiUserContact() req.Query.UserId 1988166425163862016 var ret testframe.Post2PageResult(req) golog.Info(ret) }测试流程初始化测试框架testgin.FindBeanGinTestframe()设置请求 URL 和处理方法构建查询参数执行 POST 请求并获取分页结果六、代码生成模式该模块遵循 goweb3 的代码生成模式文件命名约定文件类型命名格式示例实体{entity}.gouser_contact.go实体初始化{entity}_init.gouser_contact_init.goUI 请求ui_{entity}.goui_user_contact.goUI 请求初始化ui_{entity}_init.goui_user_contact_init.go控制器{entity}_ctl.gouser_contact_ctl.go控制器初始化{entity}_ctl_init.gouser_contact_ctl_init.go七、总结webexample模块展示了 goweb3 框架中标准 CRUD 接口的实现模式特性实现方式分层架构Model → UI Request → Controller依赖注入通过FindBeanXxx()获取单例泛型支持UiSimpleQ[Req, Entity]类型安全自动路由RegisterRoute()集中注册统一响应PageResult/IchubResult测试友好testgin测试框架支持这是 goweb3 项目中最典型的Web 服务开发模板可作为业务模块开发的参考范式