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