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

1️⃣ API 模块化设计
在小型项目中,将所有 API 写在一个文件里问题不大,但当接口数量超过 50 个时,这种方式会导致文件臃肿、难以维护、难以定位。
最佳实践:提前根据业务进行模块化拆分,并设计统一的请求封装。
推荐目录结构:
bash
/src
└── api
├── index.ts # API 请求封装和统一导出
├── auth.ts # 登录、注册、权限相关接口
├── user.ts # 用户信息相关接口
├── product.ts # 商品相关接口
└── order.ts # 订单相关接口
示例:
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 数量也会暴涨,如果全都写在一个文件里,会导致维护困难、冲突频发。
最佳实践:按业务模块拆分,并在主入口统一合并。
推荐目录结构:
css
/src
└── locales
├── index.ts
├── common.ts
├── auth.ts
├── user.ts
└── order.ts
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️⃣ 资源模块化
大型项目通常包含大量图片、图标、字体、音视频文件。
最佳实践:按业务模块拆分资源文件夹,并为资源建立索引文件,方便统一管理。
推荐目录结构:
css
/src
└── assets
├── icons
│ ├── index.ts
│ ├── user.svg
│ └── order.svg
├── images
│ ├── login_bg.png
│ └── empty_state.png
└── fonts
示例:
javascript
// assets/icons/index.ts
import UserIcon from "./user.svg";
import OrderIcon from "./order.svg";
export const Icons = {
UserIcon,
OrderIcon
}
调用:
javascript
import { Icons } from "@/assets/icons";
<img src={Icons.UserIcon} alt="用户图标" />
4️⃣ 工具模块化
工具函数是复用率最高的代码,建议提前模块化并写好单元测试。
推荐目录结构:
lua
/src
└── utils
├── index.ts
├── date.ts
├── format.ts
└── validate.ts
示例:
typescript
// 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);
调用:
javascript
import { formatDate } from "@/utils/date";
console.log(formatDate(new Date())); // 2025-09-09
5️⃣ 组件化设计
组件化是前端架构的核心。
最佳实践:将 UI 组件、业务组件分层,做到高复用、低耦合。
推荐目录结构:
css
/src
└── components
├── ui # 纯展示组件(Button, Modal, Input)
├── business # 业务组件(UserCard, OrderTable)
└── layout # 布局组件(Header, Sidebar, Footer)
示例:
javascript
// 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 组件和业务组件分层,提升复用率。
从项目一开始就设计好这些模块,可以有效避免后期重构的成本,让团队协作更高效。