82 lines
2.9 KiB
Markdown
82 lines
2.9 KiB
Markdown
# 3.6 接口层开发（handler）
|
||
|
||
:::tip 概述
|
||
handler 是极薄委托层：`router.Bind` 反射已完成参数解析与 binding 校验，本层只做一次调用转换。**业务规则一律在 service，handler 不写逻辑。**
|
||
:::
|
||
|
||
## 标准结构
|
||
|
||
```go
|
||
// internal/handler/example.go
|
||
package handler
|
||
|
||
import (
|
||
"context"
|
||
"easygoadmin/internal/model/dto"
|
||
"easygoadmin/internal/service"
|
||
)
|
||
|
||
// CExample 案例演示控制器
|
||
type CExample struct{}
|
||
|
||
// Page 案例演示分页（GET /api/example/page），委托 service.Example.Page
|
||
func (c *CExample) Page(ctx context.Context, req *dto.ExamplePageReq) (*dto.PageData[dto.ExampleItem], error) {
|
||
return service.Example.Page(ctx, req)
|
||
}
|
||
|
||
// Add 新增案例演示（POST /api/example/add），委托 service.Example.Add
|
||
func (c *CExample) Add(ctx context.Context, req *dto.ExampleAddReq) (*dto.ExampleIdRes, error) {
|
||
return service.Example.Add(ctx, req)
|
||
}
|
||
```
|
||
|
||
## 方法签名铁律
|
||
|
||
每个对外方法签名**必须**是：
|
||
|
||
```go
|
||
func (c *CXxx) Method(ctx context.Context, req *dto.XxxReq) (*dto.XxxRes, error)
|
||
```
|
||
|
||
路由反射扫描靠这个签名识别方法并绑定请求——签名不匹配的方法不会被注册（也不会报错，表现为 404）。返回值可以是结构体指针、类型别名（如 `dto.ExampleListRes`）或 `*dto.EmptyRes`。
|
||
|
||
## 手写逻辑方法的注释规约
|
||
|
||
非标准方法（导入/导出/重置密码/分配菜单等）保留为 handler 方法，按"入参/返回/副作用"三段注释：
|
||
|
||
```go
|
||
// internal/handler/example.go
|
||
// Import 导入案例演示（POST /api/example/import），委托 service.Example.Import
|
||
// 入参：multipart 表单 xls/xlsx 文件（dto 实现 UnmarshalBody 解析文件字段）。
|
||
// 返回：导入总数、成功数、失败数及失败原因列表；错误：文件缺失或格式非法时上抛。
|
||
// 副作用：解析表格并批量写入案例演示表。
|
||
func (c *CExample) Import(ctx context.Context, req *dto.ExampleImportReq) (*dto.ExampleImportRes, error) {
|
||
return service.Example.Import(ctx, req)
|
||
}
|
||
```
|
||
|
||
## handler 不做的事
|
||
|
||
| 禁则 | 去处 |
|
||
|---|---|
|
||
| 参数解析与校验 | router.Bind（binding 标签驱动）+ dto |
|
||
| 权限判断 | authz 中间件（RouteSpec.Permission 声明） |
|
||
| 操作日志 | operation_log 中间件（RouteSpec.Log 声明） |
|
||
| 业务规则与事务 | service |
|
||
| 数据访问 | repository（经 service 调用） |
|
||
|
||
## 新控制器接入
|
||
|
||
在 `internal/router/router.go` 的 `registerControllers` 中加一条 `Bind` 声明（含 RouteSpec 表）——见下一页 [3.7 路由与元数据注册](/zh/guide/route.html)。代码生成器会自动完成这一步。
|
||
|
||
## 编写检查清单
|
||
|
||
- [ ] 控制器名 `CXxx`，空结构体
|
||
- [ ] 方法与 dto 请求结构一一对应，签名完全匹配
|
||
- [ ] 方法体只有一行委托（或极少量调用转换）
|
||
- [ ] 注释给出路由方法与路径
|
||
|
||
## 下一步
|
||
|
||
→ [3.7 路由与元数据注册（RouteSpec）](/zh/guide/route.html)
|