前端-业务-架构

前端 · 业务 · 架构指南

在构建大型前端项目之前，做好基础业务模块的设计与拆分至关重要。合理的架构可以支持业务快速扩展，降低后期重构成本，提高团队协作效率。本文将从 API 模块化、国际化模块化、资源模块化、工具模块化、组件化 等方面，给出设计思路和示例，帮助你从一开始就搭建可维护、可扩展的项目结构。

---

架构图

1️⃣ API 模块化设计

在小型项目中，将所有 API 写在一个文件里问题不大，但当接口数量超过 50 个时，这种方式会导致文件臃肿、难以维护、难以定位。
最佳实践：提前根据业务进行模块化拆分，并设计统一的请求封装。

推荐目录结构：

/src

└── api

├── index.ts          # API 请求封装和统一导出

├── auth.ts           # 登录、注册、权限相关接口

├── user.ts           # 用户信息相关接口

├── product.ts        # 商品相关接口

└── order.ts          # 订单相关接口

示例：

// api/index.ts
import axios from "axios";

const http = axios.create({
  baseURL: "/api",
  timeout: 10000,
});

// 拦截器示例
http.interceptors.response.use(
  (res) => res.data,
  (err) => Promise.reject(err)
);

export default http;

// api/user.ts
import http from "./index";

export const getUserInfo = () => http.get("/user/info");
export const updateUserProfile = (data: any) => http.post("/user/update", data);
import { getUserInfo } from "@/api/user";

const user = await getUserInfo();

2️⃣ 国际化模块化

随着业务增长，国际化 key-value 数量也会暴涨，如果全都写在一个文件里，会导致维护困难、冲突频发。

最佳实践：按业务模块拆分，并在主入口统一合并。

推荐目录结构：

/src
 └── locales
      ├── index.ts
      ├── common.ts
      ├── auth.ts
      ├── user.ts
      └── order.ts

// locales/common.ts
export default {
  "app.title": "管理后台",
  "button.save": "保存",
  "button.cancel": "取消"
}

// locales/auth.ts
export default {
  "auth.login": "登录",
  "auth.logout": "退出登录"
}

// locales/index.ts
import common from "./common";
import auth from "./auth";
import user from "./user";

export default {
  ...common,
  ...auth,
  ...user
}

import { useTranslation } from "react-i18next";

const { t } = useTranslation();
return <h1>{t("auth.login")}</h1>;

这样每个业务模块只维护自己的翻译文件，避免冲突。

3️⃣ 资源模块化

大型项目通常包含大量图片、图标、字体、音视频文件。

最佳实践：按业务模块拆分资源文件夹，并为资源建立索引文件，方便统一管理。

推荐目录结构：

/src
 └── assets
      ├── icons
      │    ├── index.ts
      │    ├── user.svg
      │    └── order.svg
      ├── images
      │    ├── login_bg.png
      │    └── empty_state.png
      └── fonts

示例：

// assets/icons/index.ts
import UserIcon from "./user.svg";
import OrderIcon from "./order.svg";

export const Icons = {
  UserIcon,
  OrderIcon
}

调用：

import { Icons } from "@/assets/icons";

<img src={Icons.UserIcon} alt="用户图标" />

4️⃣ 工具模块化

工具函数是复用率最高的代码，建议提前模块化并写好单元测试。

推荐目录结构：

/src
 └── utils
      ├── index.ts
      ├── date.ts
      ├── format.ts
      └── validate.ts

示例：

// utils/date.ts

export const formatDate = (date: Date, fmt = "YYYY-MM-DD") => {

  return dayjs(date).format(fmt);

}

// utils/validate.ts

export const isEmail = (str: string) => /\S+@\S+\.\S+/.test(str);

调用：

import { formatDate } from "@/utils/date";

console.log(formatDate(new Date())); // 2025-09-09

5️⃣ 组件化设计

组件化是前端架构的核心。

最佳实践：将 UI 组件、业务组件分层，做到高复用、低耦合。

推荐目录结构：

/src
 └── components
      ├── ui            # 纯展示组件（Button, Modal, Input）
      ├── business      # 业务组件（UserCard, OrderTable）
      └── layout        # 布局组件（Header, Sidebar, Footer）

示例：

// components/ui/Button.tsx
import React from "react";

export const Button = ({ children, onClick }) => (
  <button
    className="rounded-xl bg-blue-500 px-4 py-2 text-white hover:bg-blue-600"
    onClick={onClick}
  >
    {children}
  </button>
);

🔑 总结

一个健壮的前端架构需要：

• API 模块化：按业务拆分接口，统一请求封装。

• 国际化模块化：分模块管理翻译，避免 key 冲突。

• 资源模块化：分类存放图片/图标/字体，集中索引。

• 工具模块化：常用函数集中管理并测试。

• 组件化设计：UI 组件和业务组件分层，提升复用率。

从项目一开始就设计好这些模块，可以有效避免后期重构的成本，让团队协作更高效。