前端接口怎样约定减少返工
接口返工常从一个小变化开始：字段改名、空值范围扩大、时间单位没有写清，或者页面直接依赖了数据库实体。减少返工不等于让接口永远不变，而是让变化有版本、有校验、有明确的适配位置。前后端围绕同一份契约讨论，比各自在代码里猜字段含义更有效。
1. 先切断三种不稳定依赖
1.1 界面视图（UI View）与数据库 Schema 直接强绑定
数据库实体包含存储细节，API DTO 表达对外契约，组件模型服务于界面任务。三者可以有相似字段，却不应默认是同一个类型。后端通过 DTO 控制公开字段，前端在请求边界把 DTO 转成页面需要的模型，字段拼接、枚举映射和缺省展示就不会散落在组件里。
1.2 缺乏确切的运行时类型校验与默认兜底
TypeScript 不会检查网络上实际收到的 JSON。运行时 Schema 可以在数据进入状态管理之前发现缺字段、错误类型和未知枚举。校验失败后是拒绝整页、降级局部组件还是继续使用旧缓存，应由业务场景决定，不能一律返回一份看似正常的假数据。
1.3 GraphQL / REST API 粒度失衡
接口粒度要围绕用户任务决定。页面为一次操作拼装多个独立请求时，需要处理部分成功、加载顺序和一致性；返回过多无关字段，又会增加传输和兼容负担。REST 或 GraphQL 只是表达方式，关键是页面所需数据能否在合理次数内取得，以及各字段是否有稳定语义。
2. 在网络边界完成校验与适配
Data Adapter 把 DTO 到 ViewModel 的转换集中在一处，Zod 负责验证运行时输入。它们能缩小变化范围，但前提是 API 仍遵守约定。字段语义发生改变时，适配器也需要版本判断和测试；数据库内部改动若不影响 DTO，则不应波及前端。
3. Zod + TypeScript 强校验适配器代码实现
下面的示例展示了 Schema、ViewModel 和双向适配器的基本形状。
import { z } from 'zod';
// 1. 定义后端原始 DTO Schema (与 API 返回结构一致)
export const UserApiDtoSchema = z.object({
user_id: z.number(),
first_name: z.string(),
last_name: z.string(),
avatar_url: z.string().nullable().optional(),
status_code: z.enum(['ACTIVE', 'INACTIVE', 'SUSPENDED']),
created_at_timestamp: z.number(),
});
export type UserApiDto = z.infer<typeof UserApiDtoSchema>;
// 2. 定义前端 React 组件所需的领域模型 (Domain Model)
export interface UserViewModel {
id: string;
fullName: string;
avatar: string;
isActive: boolean;
registerDateStr: string;
}
// 3. 实现双向适配器 Adapter
export class UserDataAdapter {
// 正向转换：后端 DTO -> 前端 React View Model
public static toViewModel(rawApiData: unknown): UserViewModel {
// 使用 Zod 进行运行时安全 Parse
const parseResult = UserApiDtoSchema.safeParse(rawApiData);
if (!parseResult.success) {
console.error('[API Schema Guard Alert] 接口返回异常字段:', parseResult.error.format());
// 返回安全的兜底数据，阻断 React 崩溃
return {
id: '0',
fullName: '未知用户',
avatar: '/assets/default-avatar.png',
isActive: false,
registerDateStr: '1970-01-01',
};
}
const dto = parseResult.data;
// 格式化与业务逻辑清洗
return {
id: String(dto.user_id),
fullName: `${dto.first_name} ${dto.last_name}`.trim(),
avatar: dto.avatar_url || '/assets/default-avatar.png',
isActive: dto.status_code === 'ACTIVE',
registerDateStr: new Date(dto.created_at_timestamp).toLocaleDateString(),
};
}
// 逆向转换：前端 React Form -> 后端 Mutation DTO
public static toMutationPayload(viewModel: Partial<UserViewModel>): Record<string, any> {
const nameParts = (viewModel.fullName || '').split(' ');
return {
first_name: nameParts[0] || '',
last_name: nameParts.slice(1).join(' ') || '',
status_code: viewModel.isActive ? 'ACTIVE' : 'INACTIVE',
};
}
}
在 React 组件中消费适配器：
import React, { useEffect, useState } from 'react';
import { UserDataAdapter, UserViewModel } from './UserDataAdapter';
export const UserProfileCard: React.FC<{ userId: string }> = ({ userId }) => {
const [user, setUser] = useState<UserViewModel | null>(null);
useEffect(() => {
fetch(`/api/v1/users/${userId}`)
.then((res) => res.json())
.then((data) => {
// 通过 Adapter 转换数据
const safeUser = UserDataAdapter.toViewModel(data);
setUser(safeUser);
});
}, [userId]);
if (!user) return <div>加载中…</div>;
return (
<div className="user-card">
<img src={user.avatar} alt={user.fullName} />
<h3>{user.fullName}</h3>
<span>{user.isActive ? '在线' : '离线'}</span>
</div>
);
};
4. 示例代码仍有几处契约空白
created_at_timestamp 没有说明秒还是毫秒，也没有约定时区；直接交给 Date 并使用 toLocaleDateString()，结果会受浏览器区域设置影响。契约应明确时间格式，显示格式则由产品的区域设置决定。
校验失败时返回 id: '0' 和固定日期，会把“接口数据无效”伪装成一个真实用户，后续操作可能针对错误对象。更安全的选择是返回可区分的失败结果，让页面展示错误或使用明确标记的占位模型。错误详情上报也要控制内容，避免把完整响应写进日志。
反向适配通过空格拆分姓名是有损转换，不适用于所有姓名结构。编辑表单应保留后端需要的独立字段，或由接口直接接受页面定义的明确输入类型。Record<string, any> 也应换成 Mutation Schema。组件中的 fetch 还缺少 HTTP 状态判断、取消和竞态处理：快速切换 userId 时，旧请求可能后返回并覆盖新用户。
这些缺口不否定适配层，而是说明适配器本身也是契约的一部分，需要单元测试和失败策略。
5. 前后端接口契约制定四大规则
接口约定可以落到四项可验证规则：
验收时用同一组正常、缺字段、空值、未知枚举和旧版本响应测试 Schema、Adapter 与组件。再把契约生成或检查放进前后端 CI。返工无法被完全消除，但变化会在边界处尽早暴露，不再等到页面渲染时才变成一次难以定位的 undefined。
