前端跨业务线代码复用标准化体系构建与实践

前言

在业务快速发展过程中，跨业务线功能复用 已成为提升研发效率、降低维护成本的核心诉求。当前团队主要通过微前端 、代码拷贝 两种方式实现复用，但受各业务线应用技术栈、编码规范、目录结构、依赖管理、API 格式不统一等问题限制，复用门槛高、落地效率低、代码维护成本持续攀升。

为解决这一痛点，本文全面梳理各业务线前端编码现状，制定统一的技术栈、编码规范、目录结构、依赖管理、API 格式，构建跨业务线、跨端可复用的前端标准化体系，最终实现代码高效复用、研发标准化、协作低成本的目标。

一、方案背景与目标

1.1 业务痛点

1. 复用方式受限：微前端 / 代码拷贝受容器、编码、依赖差异影响，跨业务线落地门槛高
2. 架构不统一：各业务线技术栈、目录结构、编码规范、依赖管理、API 格式各行其是
3. 复用成本极高：重复开发多、新人上手慢、模块迁移难、维护成本居高不下
4. 标准化缺失：无统一页面模板，无法实现跨业务线大规模标准化落地

1.2 核心目标

1. 现状梳理：全面盘点各业务线技术栈、编码规范、目录结构、依赖管理、API 格式
2. 范式统一 ：基于现状输出 React + TS 统一编码规范、目录结构的规范体系：可参考：前端 React + TypeScript 编码规范、前端多团队协作场景下的目录规范与代码最佳实践
3. 能力复用 ：构建多场景代码复用方案，支持跨业务线快速迁移与复用，可参考：前端差异化开发（多场景、市场、角色）：从架构到配置化实践全指南
4. 跨端兼容：兼容 React Native 移动端，最大化拉通复用能力

二、整体架构设计

2.1 架构总览

本方案采用分层标准化 + 微模块化设计 ，从技术栈、编码规范、目录结构、依赖管理、API 格式 五大维度实现标准化，最终支撑跨业务线代码复用、跨端兼容、快速迁移。
业务应用层
复用能力层
标准化核心层
技术栈统一

React + TS + 统一规范
微模块化目录结构

统一分层设计
三方依赖统一

公共库 NPM 管理
编码规范统一

ESLint + StyleLint
API 响应标准化

前端适配层统一格式
跨业务线代码复用
功能模块快速迁移
跨端兼容

Web + RN
业务线 A
业务线 B
业务线 C
业务线 D
RN 移动端

三、核心标准化方案

3.1 技术栈统一方案

各业务线核心技术栈完全对齐，仅 CSS 模块化因 RN 限制无法统一，其余能力全部拉通：

技术项	业务线 A	业务线 B	业务线 C	业务线 D	移动端	统一结论
React	✓	✓	✓	✓	React Native	统一核心框架
Vue	✓	✓	✓	✓	-	保留兼容
TypeScript	✓	✓	✓	✓	✓	强制定义统一
CSS 模块化	CSS Modules + LESS	CSS Modules / CSS-in-JS	-	-	CSS-in-JS	Web 统一，RN 灵活兼容

3.2 微模块化目录结构设计

3.2.1 各业务线现状盘点

当前各业务线目录结构差异大，简单 / 复杂页面分层无统一标准：

• 业务线 A：分层最完善，支持简单 / 复杂页面拆分
• 业务线 B：结构极简，无统一分层
• 业务线 C / D：自定义文件命名，无标准规范

3.2.2 统一设计原则

放弃传统按文件职能分类 ，采用微模块化设计：

1. 一级分类 ：按业务功能模块划分
2. 次级分类：按文件职能划分
3. 设计原则：微模块化、就近原则、高内聚低耦合
4. 核心优势：开发聚焦、便于迁移、避免巨石应用、复用性强

3.2.3 统一目录结构标准

xx-page/
├── index.tsx              # 页面主入口（视图渲染）
├── index.module.less      # 样式文件（CSS Modules）
├── components/            # 页面私有组件
├── hooks/                 # 页面私有 hooks
├── api.ts                 # 接口请求 + 适配器
├── types.ts               # TS 类型定义
├── constants.ts           # 常量配置
├── schema.tsx             # 表单 / 列表配置（可选）
└── utils.ts               # 工具函数（可选）

xx-page 业务模块
页面入口层
组件层
自定义Hooks
接口层
类型定义
常量
工具函数
表单配置
样式文件
index.tsx
通用业务组件
页面逻辑封装
请求适配器
TS类型定义
常量配置
表单列表配置
index.module.less

3.3 三方依赖统一管理

3.3.1 现状问题

1. 外部库（dayjs / ahooks / lodash 等）已统一
2. 内部公共能力（hooks / utils / types / const）分散管理，无统一出口
3. 各业务线重复造轮子，维护成本高

3.3.2 整合方案

1. 公共能力收敛 ：将通用 hooks、工具函数、类型、常量迁移至统一 NPM 公共库
2. 统一引入规范：所有业务线通过包名引入，禁止本地复制
3. 差异化管理：业务独有能力单独发包，不污染公共库

统一引入示例

// 标准用法（所有业务线一致）
import { useTable } from '@spc/shared-hooks';
import { formatDate } from '@spc/shared-utils';
import { OrderType } from '@spc/shared-types';

3.4 编码规范统一落地

3.4.1 现状

1. 基础编码规范已统一，可参考：前端编码规范完整版｜基础语法 + 双框架 + 工程化全涵盖
2. React + TS 专项规范、StyleLint 未全面落地
3. 无强制校验机制，规范执行靠人工

3.4.2 标准化执行方案

1. 输出统一规范 ：前端 React + TypeScript 编码规范
2. 公共 Lint 包：统一 ESLint + StyleLint 规则，各业务线直接继承
3. 增量检测：仅校验新增 / 修改代码，不影响存量代码
4. 提交拦截：husky + lint-staged 自动校验，保证规范落地

接入配置示例

// .eslintrc.js（所有业务线统一）
module.exports = {
  extends: [
    '@spc/lint-react-ts', // 统一规范包
  ],
};

3.4.3 增量检测冲突解决方案

• 问题：分支合并 / 冲突解决时，暂存区包含非需求代码，导致 Lint 报错
• 方案：冲突修复后使用 git commit -n 临时跳过校验，风险可控

3.5 API 响应格式标准化

3.5.1 现状痛点

1. 后端接口有基础规范，但落地难
2. 各业务线响应格式混乱（status / retcode / info / message 混用）
3. 列表 / 详情接口无统一结构

3.5.2 方案一：后端统一标准格式（需要后端配合，推动难度大）

列表查询标准

interface ListResponse<T> {
  retcode: number;
  message: string;
  data: {
    list: T[];          // 必选
    total: number;      // 总数
    count: number;      // 页大小
    pageno: number;     // 当前页
    extra?: Record<string, any>;
  };
}

详情接口标准

interface DetailResponse<T> {
  retcode: number;
  message: string;
  data: T; // 资源信息直接平铺
}

3.5.3 方案二：前端适配层统一转换（无需后端改造，低成本落地）

对历史非标准接口自动转换为标准格式，新接口强制遵循标准。

// 统一请求适配器
const request = async <T>(url: string, options?: RequestOptions) => {
  const res = await fetch(url, options);
  const data = await res.json();
  // 自动标准化
  return normalizeResponse(data);
};
// 兼容各业务线非标准格式
const normalizeResponse = (res: any) => {
  // 业务线 B 兼容
  if (res.list) {
    return {
      retcode: res.retcode ?? res.status,
      message: res.message ?? res.info,
      data: { list: res.data.list, total: res.data.total },
    };
  }
  // 业务线 D 兼容
  if (res.offset !== undefined) {
    return {
      retcode: 0,
      message: 'success',
      data: {
        list: res.list,
        total: res.total,
        pageno: res.offset / res.size + 1,
      },
    };
  }
  return res;
};

四、技术目标与落地规划

4.1 短期目标

业务目标

1. 支持部分模块或页面的跨应用迁移
2. 输出统一模板，完成部分业务跨业务线复用

技术目标

1. 前端编码规范统一落地，全业务线接入公共 Lint
2. 前端微模块化目录结构统一落地
3. API 适配层完成，统一响应格式

4.2 中长期目标

1. 完全抹平技术差异：技术栈、编码规范、目录结构、依赖管理、API 格式全部统一
2. 真正跨业务线复用：组件、模块、页面开箱即用
3. 降低研发门槛：新人快速上手，跨团队协作零成本

五、核心挑战与解决方案

核心挑战	解决方案
技术栈不完全一致	统一 React + TS 核心，CSS 方案灵活兼容
目录结构混乱	微模块化设计，强制统一目录标准
三方依赖分散	公共能力收敛至统一 NPM 包
规范落地难	统一 Lint + 增量检测 + 提交拦截
API 格式不统一	前端适配层自动标准化，低成本落地

六、预期收益

1. 研发效率大幅提升：跨业务线直接复用，减少重复开发
2. 维护成本显著降低：统一规范，代码可读性 / 可维护性增强
3. 迁移成本趋近于零：标准化结构，模块一键迁移
4. 协作体验全面优化：新人上手快、跨业务线协作无壁垒

七、总结

本方案以标准化 为核心，以微模块化 为设计理念，从技术栈、编码规范、目录结构、依赖管理、API 格式 五大维度完成统一，彻底解决前端跨业务线复用难、维护难、迁移难的问题。

方案具备低成本落地、兼容历史存量、面向未来扩展的优势，既能快速支撑当前业务复用需求，也能为后续跨端复用、工程化体系升级奠定坚实基础。