前端接口怎样约定减少返工-平芜编程栈

前端接口怎样约定减少返工

接口返工常从一个小变化开始：字段改名、空值范围扩大、时间单位没有写清，或者页面直接依赖了数据库实体。减少返工不等于让接口永远不变，而是让变化有版本、有校验、有明确的适配位置。前后端围绕同一份契约讨论，比各自在代码里猜字段含义更有效。

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时，旧请求可能后返回并覆盖新用户。

这些缺口不否定适配层，而是说明适配器本身也是契约的一部分，需要单元测试和失败策略。