定位：接口返回视图，不是表

核心判断：

前端组件的 props 来自哪个接口，那个接口就只返回这个组件需要的字段。 两个页面要的字段差很多 → 就该是两个接口（或一个接口带 view 参数），不是返回整条记录让前端自己挑。

一、增删改查各管什么

最重要的一条

前端校验是体验，后端校验是安全。 前端校验永远可以被绕过（改请求、直接 curl）。

所以分工是：

agent 常犯的错：前端 if (form.status === 3) return 就以为不能删了，后端不校验。这是漏洞。

二、三套 DTO（这是本节的核心）

以 users 表 30 个字段为例：

数据库 30 字段
├─ 列表视图   6 字段    id username nickname phone(脱敏) status createdAt
├─ 详情视图  15 字段    + email role avatarUrl lastLoginAt idCardNo(脱敏) ...
└─ 编辑表单   5 字段    nickname email role status（可写）

2.1 列表项（精简）

type UserListItem struct {
    ID        uint   `json:"id"`
    Username  string `json:"username"`
    Nickname  string `json:"nickname"`
    Phone     string `json:"phone"`       // 已脱敏
    Status    int8   `json:"status"`
    CreatedAt string `json:"createdAt"`   // RFC3339
}

列表页永远不带：大字段（头像 base64、富文本）、敏感字段（密码、身份证完整值）、关联对象全量。

2.2 详情（完整但按权限脱敏）

type UserDetail struct {
    UserListItem
    Email       string `json:"email"`
    Role        string `json:"role"`
    AvatarURL   string `json:"avatarUrl"`
    LastLoginAt string `json:"lastLoginAt"`
    IDCardNo    string `json:"idCardNo"`   // 按角色决定完整或脱敏
}

2.3 编辑请求（可写字段，与可读字段严格分离）

type UserUpdateReq struct {
    Nickname string `json:"nickname" binding:"max=32"`
    Email    string `json:"email"    binding:"omitempty,email"`
    Role     string `json:"role"     binding:"omitempty,oneof=admin user"`
    Status   *int8  `json:"status"   binding:"omitempty,oneof=0 1"`
}

为什么不能直接用 model 接请求：

1. 前端可以传 role: admin 提权（批量赋值漏洞）
2. 前端可以传 balance: 999999
3. 前端可以传 id 覆盖别的记录

可写字段清单必须显式枚举，没在 DTO 里的字段前端传了也会被忽略。

2.4 三个 DTO 的实际收益

三、脱敏：这是权限问题，不是技术问题

3.1 绝对禁止前端做脱敏

// ❌ 掩耳盗铃：数据已经在浏览器里了
const masked = phone.replace(/(\d{3})\d{4}(\d{4})/, '$1****$2')

打开 Network 面板，原始手机号一览无余。脱敏必须后端做。

3.2 标准脱敏规则

3.3 按角色分级（关键）

脱敏不是"永远脱敏"，而是按当前用户对该字段的权限决定：

func MaskPhone(phone string, full bool) string {
    if full || len(phone) < 7 {
        return phone
    }
    return phone[:3] + "****" + phone[len(phone)-4:]
}

// 在 service 组装 DTO 时按角色决定
detail.Phone = MaskPhone(u.Phone, viewer.CanSeeFull("user.phone"))

权限判定放在 service，不在 handler——因为它是业务规则。

四、配置分三层，接口也要分三档

4.1 公共配置不要带 token

// 路由分组：公开组不挂 JWT 中间件
public := r.Group("/api")
{
    public.GET("/config/public", h.Config.Public)   // 未登录也能取
    public.POST("/auth/login", h.Auth.Login)
}

authed := r.Group("/api", middleware.JWT())
{
    authed.GET("/config/me", h.Config.Me)          // 需要登录
    authed.GET("/users", h.User.List)
}

agent 常犯的错：把公共配置也挂在鉴权组里，导致登录页拿不到站点名和 logo。

4.2 什么该打包进前端，什么该走接口

4.3 私有配置的边界

// ❌ 错：把内部参数返回给前端
type AdminConfig struct {
    DBHost     string `json:"dbHost"`      // 绝对不行
    SMTPPass   string `json:"smtpPass"`    // 绝对不行
    FeatureFlag bool  `json:"featureFlag"` // 可以
}

私有配置里只返回"前端需要用来做 UI 决策"的开关，不返回任何基础设施信息。

五、批量操作：一个接口，不是循环调用

// ❌ agent 常这么写：20 条删 20 次
for (const id of selectedIds) {
  await api.deleteUser(id)
}

问题：20 次网络往返、20 个事务、20 条审计、部分成功时状态不一致。

正确：

DELETE /api/users       body: { "ids": [1,2,3] }
→ { code:0, data: { success: [1,2], failed: [{id:3, reason:"有未完成订单"}] } }

func (s *UserService) BatchDelete(ctx context.Context, ids []uint) (dto.BatchResult, error) {
    var res dto.BatchResult
    return res, s.tx.Transaction(ctx, func(tx *gorm.DB) error {
        for _, id := range ids {
            if err := s.deleteOne(tx, id); err != nil {
                res.Failed = append(res.Failed, dto.BatchFail{ID: id, Reason: err.Error()})
                continue                     // 单条失败不影响其他
            }
            res.Success = append(res.Success, id)
        }
        return nil                            // 全部失败也返回 200，明细在 data 里
    })
}

设计要点：

• 一次事务
• 返回成功/失败明细，让前端能精确提示
• 部分失败不回滚全部（除非业务要求原子性）
• 单次批量上限（如 200 条），超了拒绝

六、前端不该做的六件事

关于第 1 条（最高频）

// ❌ 拉 1000 条到前端算
const { data } = useQuery(['orders'], () => api.listOrders({ pageSize: 1000 }))
const total = data.list.reduce((s, o) => s + o.amount, 0)

// ✅ 后端返回聚合
const { data } = useQuery(['order-stats'], () => api.orderStats(params))
// { totalAmount: 128900.00, count: 1000 }

原则：能一次 SQL 算出来的，不要拉全量到前端算。

七、后端不该做的三件事

但有一条例外：状态文案建议后端返回 code，前端映射；如果文案涉及业务规则（如"已超时"依赖当前时间），那就后端算好返回 statusText。判断标准：这个文案需要业务知识才能算出来吗？

八、接口清单模板（写代码前先填）

# 用户模块

| 方法 | 路径 | 鉴权 | 请求 | 响应 data | 备注 |
|---|---|---|---|---|---|
| GET | /api/config/public | 无 | — | {siteName, logo, icp} | 未登录可访问 |
| POST | /api/auth/login | 无 | {username,password} | {accessToken, user, permissions} | 限流 5次/分 |
| GET | /api/users | JWT | ?page&pageSize&keyword&status | {page,pageSize,total,list:UserListItem[]} | 列表视图，6 字段 |
| GET | /api/users/:id | JWT | — | UserDetail | 按角色脱敏 |
| POST | /api/users | JWT+perm | UserCreateReq | {id} | 可写字段白名单 |
| PUT | /api/users/:id | JWT+perm | UserUpdateReq | null | 只允许改 5 个字段 |
| DELETE | /api/users/:id | JWT+perm | — | null | 软删 + 级联检查 |
| DELETE | /api/users | JWT+perm | {ids:[]} | {success[],failed[]} | 批量，上限 200 |

填不出这一张表，就说明职责还没想清楚，不要开始写代码。

九、验收清单

DTO 分离

• 列表接口返回的是精简 DTO，不是 model
• 详情接口返回的是脱敏 DTO
• 创建/更新用的是独立 *Req 结构，字段白名单显式枚举
• 没有任何接口直接序列化 model
• 可写字段 ≠ 可读字段（role、balance、status 等不能随便写）

脱敏

• 手机号/身份证/银行卡在后端脱敏
• 前端代码里没有脱敏正则
• 脱敏按角色分级，不是一刀切
• 密码字段是 json:"-"
• 详情接口校验了"能不能看这一条"，不只是"能不能登录"

配置

• 公共配置接口不需要 token
• 登录后配置按用户返回
• 私有配置不包含任何基础设施信息（host/password/key）
• 枚举字典打包在前端，站点配置走接口

批量与计算

• 批量操作是单接口 + 明细返回，不是前端循环
• 没有把全量数据拉到前端做统计/聚合
• 金额、折扣、税费由后端计算返回

校验

• 前端校验之后，后端仍然做了业务校验
• 唯一性、状态合法性、额度、库存都在后端校验

十、反面清单

1. ❌ 列表接口 SELECT * 后直接返回 model
2. ❌ 用 model 接收请求体（批量赋值漏洞）
3. ❌ 前端 phone.replace(...) 做脱敏
4. ❌ 所有字段永远脱敏，不按角色分级
5. ❌ 公共配置接口要求登录
6. ❌ 把 DB 地址、SMTP 密码放进"配置接口"
7. ❌ 批量删除在前端循环调单个接口
8. ❌ 拉 1000 条订单在前端 reduce 算总额
9. ❌ 前端校验了就不在后端校验
10. ❌ 隐藏了按钮就不校验接口权限