160 lines
6.3 KiB
Markdown
160 lines
6.3 KiB
Markdown
# 3.5 业务层开发（service）
|
||
|
||
:::tip 概述
|
||
service 是业务逻辑的唯一去处。标准五方法（Page/List/Detail/Add/Update/Delete/BatchDelete）通过声明 `ModuleSpec` 委托基座，差异全部进声明字段与钩子；写不进钩子的复杂逻辑手写方法，合法逃生舱。
|
||
:::
|
||
|
||
## 标准结构（三段式）
|
||
|
||
```go
|
||
// internal/service/example.go
|
||
package service
|
||
|
||
// sExample 案例演示业务实现（空结构体仅作方法命名空间，不持有状态）
|
||
type sExample struct{}
|
||
|
||
func init() {
|
||
Example = &sExample{}
|
||
}
|
||
|
||
// Example 案例演示业务实例（handler 层引用）
|
||
var Example *sExample
|
||
```
|
||
|
||
跨模块调用同包直调，无需 import：`User.Page(...)`、`repository.NewDeptRepo()`。
|
||
|
||
## ModuleSpec 声明
|
||
|
||
```go
|
||
// internal/service/example.go
|
||
var exampleSpec = ModuleSpec[dto.ExampleItem, dto.ExampleItem, dto.ExampleDetailRes]{
|
||
Model: func(ctx context.Context) *gorm.DB { return repository.NewExampleRepo().Ctx(ctx) },
|
||
LikeFields: []string{"name"}, // name 模糊，空串跳过
|
||
EqFields: []string{"type", "status"}, // 等值过滤，零值跳过
|
||
OrderBy: "sort, id", // 默认排序
|
||
SerializeMaps: exampleSerializeMaps, // status → 字典 example_status 回填 statusText
|
||
FileFields: []string{"avatar"}, // 单图：写侧 temp 转正，读侧补域名
|
||
FileSaveDir: "example", // 转正到 upload/example
|
||
ToData: exampleToData, // req → 萃库 map
|
||
}
|
||
```
|
||
|
||
泛型三参数：行结构 `Item`、列表元素 `LItem`（树形时可不同于 Item）、详情结构 `DRes`。
|
||
|
||
## 查询能力声明（固定顺序生效）
|
||
|
||
| 声明 | 生效顺序 | 行为 |
|
||
|---|---|---|
|
||
| Model | 1 | 数据源工厂，必填，通常就是 `NewXxxRepo().Ctx(ctx)` |
|
||
| LikeFields | 2 | 逐列按请求同名字段拼 LIKE，空串跳过 |
|
||
| EqFields | 3 | 等值过滤，零值跳过（需精确匹配零值的条件写 Filter） |
|
||
| KeywordFields | 4 | 请求 keyword 字段对多列 LIKE，括号包成单个 AND |
|
||
| Filter | 5 | 复杂条件追加（禁止重复声明前四项已覆盖的条件） |
|
||
| DataScope | 6 | 数据权限：`DataScope: ApplyDataScope("dept_id")` |
|
||
|
||
排序链：请求 `orderField` 命中 `OrderableFields` 白名单时前端排序生效，否则用 `OrderBy`。白名单是排序列注入的唯一防线。
|
||
|
||
## 输出与写入声明
|
||
|
||
| 声明 | 行为 |
|
||
|---|---|
|
||
| SerializeMaps | 键为枚举字段（snake），值为字典编码；读侧自动回填 `{field}Text` |
|
||
| FileFields / MultiFileFields | 单文件 / 逗号分隔多文件：写侧 saveTransform 转正，读侧补访问域名 |
|
||
| ContentFields | 富文本字段：写侧占位符化，读侧经 ExpandContentFields 还原 |
|
||
| IsTree + ParentOf | 树形输出（仅 List 建树；ParentOf 返回 0 表根） |
|
||
| UniqueFields | Add/Update 前逐条唯一性预检（并发唯一性仍以数据库 uk 索引为准） |
|
||
|
||
## ToData：请求转落库字段
|
||
|
||
```go
|
||
// internal/service/example.go
|
||
func exampleToData(req any) map[string]any {
|
||
switch r := req.(type) {
|
||
case *dto.ExampleAddReq:
|
||
return map[string]any{"name": r.Name, "avatar": r.Avatar, "type": r.Type, "status": r.Status, "sort": r.Sort}
|
||
case *dto.ExampleUpdateReq:
|
||
return map[string]any{"name": r.Name, "avatar": r.Avatar, "type": r.Type, "status": r.Status, "sort": r.Sort}
|
||
}
|
||
panic(fmt.Sprintf("exampleToData: 不支持的入参类型 %T", req))
|
||
}
|
||
```
|
||
|
||
只映射业务字段——审计字段（create_user/create_time/update_user/update_time/del_flag/tenant_id）由全局钩子统一补齐，**不要在这里赋值**。
|
||
|
||
## 标准方法（委托基座）
|
||
|
||
```go
|
||
// internal/service/example.go
|
||
func (s *sExample) Page(ctx context.Context, req *dto.ExamplePageReq) (*dto.PageData[dto.ExampleItem], error) {
|
||
list, total, err := exampleSpec.Page(ctx, req, req.GetPageNo(), req.GetPageSize())
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return dto.NewPageData(req.GetPageNo(), req.GetPageSize(), total, derefSlice(list)), nil
|
||
}
|
||
|
||
func (s *sExample) Add(ctx context.Context, req *dto.ExampleAddReq) (*dto.ExampleIdRes, error) {
|
||
id, err := exampleSpec.Add(ctx, req)
|
||
if err != nil {
|
||
return nil, err
|
||
}
|
||
return &dto.ExampleIdRes{Id: id}, nil
|
||
}
|
||
|
||
func (s *sExample) Update(ctx context.Context, req *dto.ExampleUpdateReq) (*dto.EmptyRes, error) {
|
||
if err := exampleSpec.Update(ctx, req.Id, req); err != nil {
|
||
return nil, err
|
||
}
|
||
return &dto.EmptyRes{}, nil
|
||
}
|
||
|
||
func (s *sExample) Delete(ctx context.Context, req *dto.ExampleDeleteReq) (*dto.EmptyRes, error) {
|
||
if err := exampleSpec.Delete(ctx, req.Id); err != nil {
|
||
return nil, err
|
||
}
|
||
return &dto.EmptyRes{}, nil
|
||
}
|
||
```
|
||
|
||
## 手写方法（复杂逻辑）
|
||
|
||
标准方法覆盖不了的场景直接手写——这是合法逃生舱，不是妥协：
|
||
|
||
```go
|
||
// internal/service/example.go
|
||
// Status 手写单列更新（仅更新 status 一列）
|
||
func (s *sExample) Status(ctx context.Context, req *dto.ExampleStatusReq) (*dto.EmptyRes, error) {
|
||
if err := repository.NewExampleRepo().Ctx(ctx).
|
||
Where("id = ?", req.Id).Updates(map[string]any{"status": req.Status}).Error; err != nil {
|
||
return nil, err
|
||
}
|
||
return &dto.EmptyRes{}, nil
|
||
}
|
||
```
|
||
|
||
导入导出、登录、分配菜单、状态流转等都属于手写范畴。导出可复用基座过滤器 `spec.applyFilters(ctx, spec.Model(ctx), req)` 与字典查询 `DictGetText(ctx, dictCode, value)`。
|
||
|
||
## 业务错误上抛
|
||
|
||
```go
|
||
// internal/service/auth.go（实际代码）——哨兵错误直接返回
|
||
return nil, consts.CodeTenantDisabled
|
||
|
||
// internal/service/base.go（实际代码）——唯一性预检的格式化错误
|
||
return apperr.Newf(consts.CodeRecordExists.Code(), "%s已存在", label)
|
||
```
|
||
|
||
错误原样上抛，**禁止在钩子与 service 内做 HTTP 响应或文件 IO 之外的越层处理**（钩子还禁止 append 修改切片）。
|
||
|
||
## 编写检查清单
|
||
|
||
- [ ] 三段式结构（sXxx / init / var）
|
||
- [ ] 标准方法全部委托 ModuleSpec，业务差异进声明与钩子
|
||
- [ ] ToData 不映射审计字段
|
||
- [ ] 跨模块同包直调，事务用 `db.WithTrans` 且回调内用入参 ctx
|
||
- [ ] dict 模块 init 中调用 `SetDictLookup(...)` 注册字典查询（涉及字典的模块）
|
||
|
||
## 下一步
|
||
|
||
→ [3.6 接口层开发（handler）](/zh/guide/handler.html)
|