# 3.6 控制器开发

:::tip 概述
控制器是 HTTP 薄层，只做一件事：把解析好的请求转发给 service 接口。不写业务、不操作数据库、不组装复杂响应——所有逻辑在 logic 层。这个"薄"是有意为之：让权限、日志、参数解析统一收敛到 Bind 包装层。
:::

## 真实代码（摘自 internal/controller/example.go）

```go
package controller

import (
	"context"

	"easygoadmin/api/v1"
	"easygoadmin/internal/service"
)

// ============================== 案例演示控制器 ==============================

// CExample 案例演示控制器
// 薄层控制器，仅负责参数透传，业务逻辑由 service.Example() 处理
type CExample struct{}

// Page 案例演示分页
// 按查询条件分页返回案例演示列表
func (c *CExample) Page(ctx context.Context, req *v1.ExamplePageReq) (res *v1.ExamplePageRes, err error) {
	return service.Example().Page(ctx, req)
}

// List 案例演示平铺列表
// data 直接为数组，树形结构由前端 buildTree 构建
func (c *CExample) List(ctx context.Context, req *v1.ExampleListReq) (res v1.ExampleListRes, err error) {
	return service.Example().List(ctx, req)
}

// Detail 案例演示详情
// 按主键ID查询详情
func (c *CExample) Detail(ctx context.Context, req *v1.ExampleDetailReq) (res *v1.ExampleDetailRes, err error) {
	return service.Example().Detail(ctx, req)
}

// Add 新增案例演示
// 新增成功后返回新记录ID
func (c *CExample) Add(ctx context.Context, req *v1.ExampleAddReq) (res *v1.ExampleIdRes, err error) {
	return service.Example().Add(ctx, req)
}

// Update 修改案例演示
// 按主键ID更新记录
func (c *CExample) Update(ctx context.Context, req *v1.ExampleUpdateReq) (res *v1.ExampleUpdateRes, err error) {
	return service.Example().Update(ctx, req)
}

// Status 案例演示状态
// 设置记录的状态字段
func (c *CExample) Status(ctx context.Context, req *v1.ExampleStatusReq) (res *v1.ExampleStatusRes, err error) {
	return service.Example().Status(ctx, req)
}
```

## 方法签名约定

```go
func (c *CXxx) 方法名(ctx context.Context, req *v1.XxxReq) (res *v1.XxxRes, err error)
```

这是 Bind 反射绑定的硬约束：**入参必须是指针请求结构体，出参必须是（结果指针, error）**。签名不匹配的方法不会被注册路由（静默跳过），排障时注意。

## 命名规则

| 项 | 规则 | 示例 |
|----|------|------|
| 控制器类型 | `C` + 模块 Pascal | `CExample`、`CConfigItem` |
| 文件名 | 表名去前缀 snake_case | `example.go`、`config_item.go` |
| 方法名 | 与 logic/接口方法名一致 | `Page`/`Add`/`BatchDelete` |
| 包 | 单包 `controller`，平铺放置 | 无子目录 |

## 控制器里禁止做的事

::: warning 薄层纪律
1. **禁止写业务逻辑**——if/for/计算全部下沉 logic。
2. **禁止直接 import dao**——数据访问只在 logic。
3. **禁止手写响应信封**——Bind 包装层统一 `response.Ok/Fail` 包装。
4. **禁止手写参数解析/权限判断**——`r.Parse` 与 `HasPerm` 在包装层完成。
5. 需要组合多个 service 调用时，逻辑放 logic 层的一个聚合方法，controller 仍只透传。
:::

## 特殊控制器参考

| 控制器 | 特点 |
|--------|------|
| `CAuth` | 登录/登出/验证码/令牌，gmeta 带 `public:"true"` |
| `CIndex` | 个人中心聚合（getUser/getMenus/updatePassword/updateProfile） |
| `COnlineUser` | 无表模块，数据源 Redis |
| `CUpload` | multipart 上传（`*ghttp.UploadFile` + `p:"file"` 标签） |
| `CGenerator` | 工具类，Preview/Generate/BatchGenerate |

控制器不区分"标准/特殊"写法——统一薄层透传，差异全部体现在请求结构体的 gmeta 注解上。