前端架构（可移植、基于模块）

当您需要一个可移植的、与框架无关的架构风格来用于任何 React 或 React Native 前端时，使用此技能。将应用组织为具有页面/屏幕目录的功能模块，严格区分服务器状态与 UI 状态，仅限桶文件的跨模块导入，样式共置，以及明确的组件提升规则……

目标：一个代码库，任何贡献者都能立即回答三个问题 —

“这段代码存放在哪里？”、“允许导入什么？”以及“这是服务器状态还是界面状态？” —

没有问任何人。结构使答案显而易见。

以下内容都是这五个理念的机械应用。它们都不依赖于特定的库——在第4和第6部分选择你的技术栈。

形状在各个框架中是相同的；只有上层的路由层不同（见第7节）。

src/
├── app/ or routes/ or navigation/   ← framework routing layer (thin — see §7)
├── modules/                         ← feature modules (the heart of the app)
│   └── {feature}/
│       ├── index.ts                 ← PUBLIC BARREL — the only cross-module entry point
│       ├── README.md                ← what this module owns, its routes, its data deps
│       ├── components/              ← components reused by 2+ pages IN THIS MODULE
│       ├── pages/                   ← page/screen directories (one per route)
│       │   └── {page}/
│       │       ├── {page}.tsx               ← the page/screen component
│       │       ├── {page}.styles.ts         ← ALL styling for this page
│       │       ├── index.ts                 ← re-exports the page component
│       │       ├── components/              ← components used ONLY by this page
│       │       ├── hooks/                   ← hooks used ONLY by this page
│       │       ├── constants/
│       │       └── README.md                ← route, params, permissions, data deps
│       ├── hooks/                   ← data hooks (query/mutation) + module hooks
│       ├── stores/                  ← UI/client state store(s) — never server data
│       ├── services/                ← data-access (API calls) for this feature
│       ├── utils/                   ← pure module utilities (co-located *.test.ts)
│       ├── constants/
│       └── types/                   ← module request/response + view-model types
└── shared/                          ← cross-module building blocks
    ├── components/                  ← components used by 2+ MODULES
    ├── hooks/                       ← cross-cutting hooks
    ├── api-client/                  ← one typed client; the only place that talks to the network
    ├── store/                       ← root store wiring (if your state lib needs one — see §4)
    ├── utils/                       ← formatters, cn()/clsx, helpers
    ├── constants/
    └── types/

在脚手架创建时可以为空的每个文件夹都会保留一个 .gitkeep，以便从第一天起结构可见。

模块是产品的一个垂直切片（例如 auth、billing、dashboard、settings）。它包含该功能所需的一切，并暴露出刻意设计的小型接口。

modules/{feature}/index.ts 是其他模块和路由层可以导入的唯一内容。它重新导出：

// CORRECT — consume the public surface
import { InvoiceListPage, useInvoiceList } from "@/modules/invoice";

// WRONG — reaching into internals couples you to private structure
import { InvoiceListPage } from "@/modules/invoice/pages/invoice-list/invoice-list";

保持 barrel 的整理。如果某些内容没有被导出，那它天生就是私有的。将导出按照短注释分类（pages、hooks、store、types）——未来的阅读者会把 barrel 当作模块的 API 文档使用。

不要创建 utils 模块或 components 模块。模块对应产品功能，而不是技术层。技术构建模块位于 shared/。

每个模块的 README.md 都说明了：它拥有的内容、哪些路由渲染它的页面、它的数据依赖（哪些端点/钩子），以及任何跨模块的规则。这是新贡献者首先会阅读的内容。

页面是路由器挂载的一个路由（在 React Native 中是一个“屏幕”）。它总是一个文件夹，绝不是一个散文件——即使它最初只是一个单独的组件。这可以保持结构的稳定：当页面需要子组件或钩子时，已经有现成的位置放置它们。

pages/{page}/
├── {page}.tsx          ← the page/screen component
├── {page}.styles.ts    ← every style for this page (no inline styles — see §5)
├── index.ts            ← export { PageComponent } from "./{page}"
├── components/         ← used ONLY by this page
├── hooks/              ← used ONLY by this page
├── constants/
└── README.md           ← route, params, permissions, data deps

该页面的 README 简短且信息量大：路由路径、预期参数、所需权限/认证，以及它依赖的钩子。它是页面与应用其余部分之间的契约。

为什么从一开始就使用文件夹： 一个最初作为单个文件的页面不可避免地会增加子行组件、汇总钩子和样式文件。如果页面是一个文件，这些内容会散落在任意位置。如果页面是一个文件夹，它们就有了显而易见的归属，并且差异保持可读。

4. 状态：按来源拆分（不可协商，与库无关）

两种状态，两种家园。混合它们是这种技能存在所要防止的最常见的建筑失败。分离是必须的；图书馆的选择由你决定。

Server state fetched entities, lists, aggregates — anything the API owns a query/cache layer (e.g. TanStack Query, RTK Query, SWR, Apollo)

UI / client state open dialogs, table filters/sort, wizard step, draft being typed, preview toggles a client store (e.g. Zustand, Redux Toolkit, MobX, Jotai, Valtio, or React Context)

4.2 选择客户端状态库——相同的形状，不同的语法

每个项目选择一个并保持一致。每个都可以清楚地映射到“每个模块一个存储单元”。注意 I 接口命名约定：状态接口前缀为 I（例如 IFeatureUiState）。

Zustand — modules/{feature}/stores/{feature}.store.ts

import { create } from "zustand";

export interface IFeatureUiState {
  isPreviewOpen: boolean;
  filter: string;
  togglePreview: () => void;
  setFilter: (filter: string) => void;
  reset: () => void;
}

const INITIAL_STATE = { isPreviewOpen: false, filter: "" } as const;

export const useFeatureUiStore = create<IFeatureUiState>()((set) => ({
  ...INITIAL_STATE,
  togglePreview: () => set((s) => ({ isPreviewOpen: !s.isPreviewOpen })),
  setFilter: (filter) => set({ filter }),
  reset: () => set({ ...INITIAL_STATE }),
}));

Redux 工具包 — modules/{feature}/stores/{feature}.slice.ts（已在 shared/store/ 中注册）

import { createSlice, type PayloadAction } from "@reduxjs/toolkit";

export interface IFeatureUiState {
  isPreviewOpen: boolean;
  filter: string;
}

const initialState: IFeatureUiState = { isPreviewOpen: false, filter: "" };

export const featureUiSlice = createSlice({
  name: "featureUi",
  initialState,
  reducers: {
    togglePreview: (s) => {
      s.isPreviewOpen = !s.isPreviewOpen;
    },
    setFilter: (s, action: PayloadAction<string>) => {
      s.filter = action.payload;
    },
    reset: () => initialState,
  },
});

MobX — modules/{feature}/stores/{feature}.store.ts

import { makeAutoObservable } from "mobx";

export interface IFeatureUiState {
  isPreviewOpen: boolean;
  filter: string;
}

export class FeatureUiStore implements IFeatureUiState {
  isPreviewOpen = false;
  filter = "";
  constructor() {
    makeAutoObservable(this);
  }
  togglePreview = () => {
    this.isPreviewOpen = !this.isPreviewOpen;
  };
  setFilter = (filter: string) => {
    this.filter = filter;
  };
  reset = () => {
    this.isPreviewOpen = false;
    this.filter = "";
  };
}

Jotai — modules/{feature}/stores/{feature}.atoms.ts

import { atom } from "jotai";
export const isPreviewOpenAtom = atom(false);
export const filterAtom = atom("");

所有网络访问都通过 shared/api-client/ 中的一个类型化客户端进行。模块将其封装在查询/变更钩子和键工厂中，以保持缓存和失效的一致性。

// modules/invoice/hooks/invoiceKeys.ts — hierarchical key factory (TanStack Query style)
export const invoiceKeys = {
  all: ["invoices"] as const,
  lists: () => [...invoiceKeys.all, "list"] as const,
  list: (params: IListParams) => [...invoiceKeys.lists(), params] as const,
  details: () => [...invoiceKeys.all, "detail"] as const,
  detail: (id: string) => [...invoiceKeys.details(), id] as const,
} as const;

使 lists() 无效会刷新每个已过滤的页面；detail(id) 针对单个实体。（RTK Query/SWR/Apollo 用标签/键表达相同的概念。）组件从不直接调用原始的 fetch() —— 它们调用 useInvoiceList() / useCreateInvoice()。

5. 样式：共置，不使用内联样式（不依赖特定样式库）

将样式保持在 JSX 外部，并且在组件主体之外。每个页面或组件都有一个同位置样式文件。规则是固定的；语法遵循你的样式堆栈。

// invoice-list.styles.ts (Tailwind example)
export const invoiceListStyles = {
  page: "flex flex-col gap-8",
  header: "flex flex-col gap-1.5",
  title: "text-3xl font-semibold tracking-tight",
} as const;

// invoice-list.styles.ts (Tamagui example — works on web AND native)
import { styled, YStack, Text } from "tamagui";

export const InvoiceListPage = styled(YStack, { flex: 1, gap: "$8" });
export const InvoiceListHeader = styled(YStack, { gap: "$1.5" });
export const InvoiceListTitle = styled(Text, {
  fontSize: "$8",
  fontWeight: "600",
});

组件主体中不要使用内联 style={{...}} 字面量，无论在哪个技术栈中。原因：当样式内联时，会出现样式漂移和重复。一个同目录的样式文件提供了一个审查间距节奏、主题正确性以及每个界面响应式行为的地方。在该文件中用注释记录非显而易见的选择（如强调锁定、断点）。

这个技能并不决定_视觉_设计——与设计/组件技能配合使用才能做到这一点。它只决定_样式存放的位置_。

模块/页面/状态模型是固定的。只有上方的轻量路由层会发生变化。页面总是存在于 modules/ 中；路由层只是 挂载 它们。

// app/(app)/invoices/page.tsx — thin route file
import { InvoiceListPage } from "@/modules/invoice";
export default function Page() {
  return <InvoiceListPage />;
}

// app/invoices/index.tsx (Expo Router) — thin screen file
import { InvoiceListScreen } from "@/modules/invoice";
export default InvoiceListScreen;

如果你同时面向 Web 和 Expo，将无框架的代码（类型、验证器、格式化器、API 客户端契约）推送到一个供两个应用使用的共享包中，并优先使用 Tamagui 来处理必须在两者上渲染的组件。模块边界在两端保持不变。

8. 规范检查清单（在审查中执行）

9. 组件推广（从本地开始，向外扩展）

一个组件会在使用它的最狭窄范围内诞生，只有当出现第二个使用者时才会被提升。永远不要因为“它可能会被重用”而预先放置一个组件。

A component used by… Lives in Imported as

Only one page pages/{page}/components/ relative path within the page

2+ pages in one module modules/{feature}/components/ @/modules/{feature} (via barrel)

2+ modules shared/components/ @/shared/...

2+ apps / repos a published design-system package the package name

相同的层级适用于 hooks、utils 和 constants：从 local → module → shared → package。提升是一个有意的操作（更新导入位置），而不是事先做出的猜测。

Frontend Architecture 实用指南

A portable, framework-agnostic architecture style for any React or React Native frontend. Organizes apps into feature modules with page/screen directories, a strict server-state vs UI-state split, barrel-only cross-module imports, co-located styles, and clear component-promotion rules....

前端

架构设计

开发工具

前端架构实用指南：采用可移植、框架无关的模块化设计，将应用组织为功能模块与页面目录，严格分离服务器状态与UI状态，通过桶文件控制跨模块导入，样式共置并明确组件提升规则。适用于React、React Native、Next.js等主流框架，提供从目录结构到状态管理的完整操作规范。

React Native

服务器

路由器

路由

GitHub

Agent

ReAct 

2026上云采购 | AI焕新·智启新局

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

Frontend Architecture 实用指南

Frontend Architecture 实用指南

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐