feature-sliced-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Feature-Sliced Design (FSD) v2.1

Source: fsd.how | Strictness can be adjusted based on project scale and team context.

来源：fsd.how | 可根据项目规模和团队情况调整严格程度。

1. Core Philosophy & Layer Overview

1. 核心理念与层级概述

FSD v2.1 core principle: "Start simple, extract when needed."

Place code in

pages/

first. Duplication across pages is acceptable and does not automatically require extraction to a lower layer. Extract only when the team agrees it is necessary.

Not all layers are required. Most projects can start with only

shared/

pages/

, and

app/

. Add

widgets/

features/

entities/

only when they provide clear value. Do not create empty layer folders "just in case."

FSD uses 6 standardized layers with a strict top-down import direction:

text

app/       → App initialization, providers, routing
pages/     → Route-level composition, owns its own logic
widgets/   → Large composite UI blocks reused across multiple pages
features/  → Reusable user interactions (only when used in 2+ places)
entities/  → Reusable business domain models (only when used in 2+ places)
shared/    → Infrastructure with no business logic (UI kit, utils, API client)

Import rule: A module may only import from layers strictly below it. Cross-imports between slices on the same layer are forbidden.

typescript

// ✅ Allowed
import { Button } from "@/shared/ui/Button"; // features → shared
import { useUser } from "@/entities/user"; // pages → entities

// ❌ Violation
import { loginUser } from "@/features/auth"; // entities → features
import { likePost } from "@/features/like-post"; // features → features

Note: The

processes/

layer is deprecated in v2.1. For migration details, read

references/migration-guide.md

FSD v2.1核心原则：「从简开始，按需提取。」

先将代码放在

pages/

目录下。页面间的代码重复是可接受的，并不需要自动提取到更低层级。仅当团队达成共识认为有必要时，再进行提取操作。

并非所有层级都是必需的。大多数项目只需从

shared/

、

pages/

和

app/

开始即可。仅当

widgets/

、

features/

、

entities/

能带来明确价值时再添加。不要“以防万一”创建空的层级文件夹。

FSD采用6个标准化层级，且严格遵循自上而下的导入方向：

text

app/       → 应用初始化、提供者、路由配置
pages/     → 路由级别的组合代码，拥有独立逻辑
widgets/   → 可在多个页面复用的大型复合UI块
features/  → 可复用的用户交互逻辑（仅在2个及以上场景使用时）
entities/  → 可复用的业务领域模型（仅在2个及以上场景使用时）
shared/    → 无业务逻辑的基础设施（UI组件库、工具函数、API客户端）

导入规则：模块仅能从严格低于自身的层级导入代码。禁止同一层级内不同切片之间的跨导入。

typescript

// ✅ 允许
import { Button } from "@/shared/ui/Button"; // features → shared
import { useUser } from "@/entities/user"; // pages → entities

// ❌ 违规
import { loginUser } from "@/features/auth"; // entities → features
import { likePost } from "@/features/like-post"; // features → features

注意：

processes/

层级在v2.1中已被弃用。迁移细节请查看

references/migration-guide.md

。

2. Decision Framework

2. 决策框架

When writing new code, follow this tree:

Step 1 — Where is this code used?

Used in only one page → keep it in that
```
pages/
```
slice.
Used in 2+ pages but duplication is manageable → keeping separate copies in each page is also valid.
An entity or feature used in only one page → keep it in that page (Steiger:
```
insignificant-slice
```
).

Step 2 — Is it reusable infrastructure with no business logic?

UI components →
```
shared/ui/
```
Utility functions →
```
shared/lib/
```
API client, route constants →
```
shared/api/
```
or
```
shared/config/
```
Auth tokens, session management →
```
shared/auth/
```
CRUD operations →
```
shared/api/
```

Step 3 — Is it a complete user action reused in 2+ places, and does the team agree to extract it?

Yes →
```
features/
```
Uncertain or single use → keep in the page.

Step 4 — Is it a business domain model reused in 2+ places, and does the team agree to extract it?

Yes →
```
entities/
```
Uncertain or single use → keep in the page.

Step 5 — Is it app-wide configuration?

Global providers, router, theme →
```
app/
```

Golden Rule: When in doubt, keep it in
pages/
. Extract only when the team agrees.

编写新代码时，请遵循以下流程：

步骤1 — 该代码的使用范围？

仅在单个页面使用 → 保留在该页面的
```
pages/
```
切片中。
在2个及以上页面使用，但重复代码的维护成本可控 → 也可在每个页面保留独立副本。
实体或功能仅在单个页面使用 → 保留在该页面中（Steiger规则：
```
insignificant-slice
```
）。

步骤2 — 该代码是否为无业务逻辑的可复用基础设施？

UI组件 →
```
shared/ui/
```
工具函数 →
```
shared/lib/
```
API客户端、路由常量 →
```
shared/api/
```
或
```
shared/config/
```
认证令牌、会话管理 →
```
shared/auth/
```
CRUD操作 →
```
shared/api/
```

步骤3 — 该代码是否为完整的用户操作逻辑，可在2个及以上场景复用，且团队已达成提取共识？

是 →
```
features/
```
不确定或仅单个场景使用 → 保留在页面中。

步骤4 — 该代码是否为业务领域模型，可在2个及以上场景复用，且团队已达成提取共识？

是 →
```
entities/
```
不确定或仅单个场景使用 → 保留在页面中。

步骤5 — 该代码是否为应用全局配置？

全局提供者、路由、主题 →
```
app/
```

黄金法则：如有疑问，保留在
pages/
中。仅当团队达成共识时再进行提取。

3. Quick Placement Table

3. 快速放置对照表

Scenario	Single use	Multi-use (with team agreement)
User profile form	`pages/profile/ui/ProfileForm.tsx`	`features/profile-form/`
Product card	`pages/products/ui/ProductCard.tsx`	`entities/product/ui/ProductCard.tsx`
Product data fetching	`pages/product-detail/api/fetch-product.ts`	`entities/product/api/`
Auth token/session	`shared/auth/` (always)	`shared/auth/` (always)
Auth login form	`pages/login/ui/LoginForm.tsx`	`features/auth/`
CRUD operations	`shared/api/` (always)	`shared/api/` (always)
Generic Card layout	—	`shared/ui/Card/`
Modal manager	—	`shared/ui/modal-manager/`
Modal content	`pages/[page]/ui/SomeModal.tsx`	—
Date formatting util	—	`shared/lib/format-date.ts`

场景	单个场景使用	多场景使用（需团队共识）
用户资料表单	`pages/profile/ui/ProfileForm.tsx`	`features/profile-form/`
产品卡片	`pages/products/ui/ProductCard.tsx`	`entities/product/ui/ProductCard.tsx`
产品数据获取	`pages/product-detail/api/fetch-product.ts`	`entities/product/api/`
认证令牌/会话	`shared/auth/` （始终）	`shared/auth/` （始终）
认证登录表单	`pages/login/ui/LoginForm.tsx`	`features/auth/`
CRUD操作	`shared/api/` （始终）	`shared/api/` （始终）
通用卡片布局	—	`shared/ui/Card/`
模态框管理器	—	`shared/ui/modal-manager/`
模态框内容	`pages/[page]/ui/SomeModal.tsx`	—
日期格式化工具	—	`shared/lib/format-date.ts`

4. Architectural Rules (MUST)

4. 架构规则（必须遵守）

These rules are the foundation of FSD. Violations weaken the architecture. If you must break a rule, ensure it is an intentional design decision — document the reason and obtain team consensus.

这些规则是FSD的基础。违反规则会削弱架构的稳定性。如果必须打破规则，确保这是经过深思熟虑的设计决策——记录原因并获得团队共识。

4-1. Import only from lower layers

4-1. 仅从更低层级导入代码

app → pages → widgets → features → entities → shared

. Upward imports and cross-imports between slices on the same layer are forbidden.

导入方向为

app → pages → widgets → features → entities → shared

。禁止向上导入，也禁止同一层级内不同切片之间的跨导入。

4-2. Public API — every slice exports through index.ts

4-2. 公共API — 每个切片仅通过index.ts导出

External consumers may only import from a slice's

index.ts

. Direct imports of internal files are forbidden.

typescript

// ✅ Correct
import { LoginForm } from "@/features/auth";

// ❌ Violation — bypasses public API
import { LoginForm } from "@/features/auth/ui/LoginForm";

RSC / meta-framework exception: In environments with distinct client/server boundaries, split entry points are permitted (

index.client.ts

index.server.ts

). See

references/framework-integration.md

for details.

外部消费者仅能从切片的

index.ts

导入代码。禁止直接导入切片内部文件。

typescript

// ✅ 正确
import { LoginForm } from "@/features/auth";

// ❌ 违规 — 绕过了公共API
import { LoginForm } from "@/features/auth/ui/LoginForm";

RSC/元框架例外：在客户端/服务端边界明确的环境中，允许拆分入口文件（

index.client.ts

、

index.server.ts

）。详情请查看

references/framework-integration.md

。

4-3. No cross-imports between slices on the same layer

4-3. 禁止同一层级内切片间的跨导入

If two slices on the same layer need to share logic, follow the resolution order in Section 7. Do not create direct imports.

如果同一层级的两个切片需要共享逻辑，请按照第7节的解决方案顺序处理。不要创建直接导入。

4-4. Domain-based file naming (no desegmentation)

4-4. 基于领域的文件命名（避免按技术职责拆分）

Name files after the business domain they represent, not their technical role. Technical-role names like

types.ts

utils.ts

helpers.ts

mix unrelated domains in a single file and reduce cohesion.

text

// ❌ Technical-role naming
model/types.ts          ← Which types? User? Order? Mixed?
model/utils.ts

// ✅ Domain-based naming
model/user.ts           ← User types + related logic
model/order.ts          ← Order types + related logic
api/fetch-profile.ts    ← Clear purpose

根据代码所属的业务领域命名文件，而非其技术职责。像

types.ts

、

utils.ts

、

helpers.ts

这类按技术职责命名的文件会将不相关的领域代码混在一起，降低内聚性。

text

// ❌ 按技术职责命名
model/types.ts          ← 哪些类型？用户？订单？混合类型？
model/utils.ts

// ✅ 基于领域命名
model/user.ts           ← 用户类型+相关逻辑
model/order.ts          ← 订单类型+相关逻辑
api/fetch-profile.ts    ← 用途明确

4-5. No business logic in shared/

4-5.

shared/

目录中禁止包含业务逻辑

Shared contains only infrastructure: UI kit, utilities, API client setup, route constants, assets. Business calculations, domain rules, and workflows belong in

entities/

or higher layers.

typescript

// ❌ Business logic in shared
// shared/lib/userHelpers.ts
export const calculateUserReputation = (user) => { ... };

// ✅ Move to the owning domain
// entities/user/lib/reputation.ts
export const calculateUserReputation = (user) => { ... };

Shared目录仅包含基础设施：UI组件库、工具函数、API客户端配置、路由常量、资源文件。业务计算、领域规则和工作流应放在

entities/

或更高层级中。

typescript

// ❌ 业务逻辑放在shared中
// shared/lib/userHelpers.ts
export const calculateUserReputation = (user) => { ... };

// ✅ 移至所属领域
// entities/user/lib/reputation.ts
export const calculateUserReputation = (user) => { ... };

5. Recommendations (SHOULD)

5. 推荐实践（建议遵守）

5-1. Pages First — place code where it is used

5-1. 页面优先 — 代码放在使用它的位置

Place code in

pages/

first. Extract to lower layers only when truly needed. When extraction seems worthwhile, discuss with the team — this is a design decision that affects the whole project.

What stays in pages:

Large UI blocks used only in one page
Page-specific forms, validation, data fetching, state management
Page-specific business logic and API integrations
Code that looks reusable but is simpler to keep local

Evolution pattern: Start with everything in

pages/profile/

. When another page needs the same user data and the team agrees, extract the shared model to

entities/user/

. Keep page-specific API calls and UI in the page.

先将代码放在

pages/

中。仅当真正需要时再提取到更低层级。当认为提取有价值时，请与团队讨论——这是一个影响整个项目的设计决策。

保留在pages中的内容：

仅在单个页面使用的大型UI块
页面专属的表单、验证、数据获取、状态管理
页面专属的业务逻辑和API集成
看似可复用但保留在本地更简单的代码

演进模式： 先将所有代码放在

pages/profile/

中。当另一个页面需要相同的用户数据且团队达成共识时，将共享模型提取到

entities/user/

中。页面专属的API调用和UI仍保留在页面中。

5-2. Be conservative with entities

5-2. 谨慎使用entities层级

The entities layer is highly accessible — almost every other layer can import from it, so changes propagate widely.

Start without entities.
```
shared/
```
+
```
pages/
```
+
```
app/
```
is valid FSD. Thin-client apps rarely need entities.
Do not split slices prematurely. Keep code in pages. Extract to entities only when 2+ consumers are confirmed and the team agrees.
Business logic does not automatically require an entity. Keeping types in
```
shared/api
```
and logic in the current slice's
```
model/
```
segment may be sufficient.
Place CRUD in
shared/api/
. CRUD is infrastructure, not entities.
Place auth data in
shared/auth/
or
shared/api/
. Tokens and login DTOs are auth-context-dependent and rarely reused outside authentication.

Entities层级的可访问性极高——几乎所有其他层级都可以从它导入代码，因此该层级的变更会广泛传播。

先不使用entities。
```
shared/
```
+
```
pages/
```
+
```
app/
```
就是有效的FSD结构。轻客户端应用几乎不需要entities层级。
不要过早拆分切片。将代码保留在页面中。仅当确认有2个及以上消费者且团队达成共识时，再提取到entities层级。
业务逻辑不一定要用entities。将类型放在
```
shared/api
```
中，逻辑放在当前切片的
```
model/
```
段中可能就足够了。
将CRUD操作放在
shared/api/
中。CRUD是基础设施，不属于entities。
将认证数据放在
shared/auth/
或
shared/api/
中。令牌和登录DTO依赖于认证上下文，很少在认证场景外复用。

5-3. Start with minimal layers

5-3. 从最小化层级开始

text

// ✅ Valid minimal FSD project
src/
  app/         ← Providers, routing
  pages/       ← All page-level code
  shared/      ← UI kit, utils, API client

// Add layers only when the team decides they are needed:
// + widgets/   ← UI blocks reused in 2+ pages
// + features/  ← User interactions reused in 2+ pages
// + entities/  ← Domain models reused in 2+ pages/features

text

// ✅ 有效的最小化FSD项目
src/
  app/         ← 提供者、路由
  pages/       ← 所有页面级代码
  shared/      ← UI组件库、工具函数、API客户端

// 仅当团队认为需要时再添加层级：
// + widgets/   ← 在2个及以上页面复用的UI块
// + features/  ← 在2个及以上页面复用的用户交互
// + entities/  ← 在2个及以上页面/功能复用的领域模型

5-4. Validate with the Steiger linter

5-4. 使用Steiger代码检查器验证

Steiger is the official FSD linter. Key rules:

insignificant-slice
: Suggests merging an entity/feature into its page if only one page uses it.
excessive-slicing
: Suggests merging or grouping when a layer has too many slices.

bash

npm install -D @feature-sliced/steiger
npx steiger src

Steiger是官方FSD代码检查器。核心规则：

insignificant-slice
：如果某个实体/功能仅被一个页面使用，建议将其合并到所属页面中。
excessive-slicing
：当某个层级的切片过多时，建议合并或分组。

bash

npm install -D @feature-sliced/steiger
npx steiger src

6. Anti-patterns (AVOID)

6. 反模式（避免使用）

Do not create entities prematurely. Data structures used in only one place belong in that place.
Do not put CRUD in entities. Use
```
shared/api/
```
. Consider entities only for complex transactional logic.
Do not create a
user
entity just for auth data. Tokens and login DTOs belong in
```
shared/auth/
```
or
```
shared/api/
```
.
Do not abuse @x. It is a last resort, not a recommended pattern (see Section 7).
Do not extract single-use code. A feature or entity used by only one page should stay in that page.
Do not use technical-role file names. Use domain-based names (see Rule 4-4).
Be cautious adding UI to entities. Entity UI tempts cross-imports from other entities. If you add UI segments to entities, only import them from higher layers (features, widgets, pages) — never from other entities.
Do not create god slices. Slices with excessively broad responsibilities should be split into focused slices (e.g., split
```
user-management/
```
into
```
auth/
```
,
```
profile-edit/
```
,
```
password-reset/
```
).

不要过早创建entities。仅在单个场景使用的数据结构应保留在该场景中。
不要将CRUD操作放在entities中。使用
```
shared/api/
```
。仅当涉及复杂事务逻辑时再考虑entities。
不要只为了认证数据创建
user
实体。令牌和登录DTO应放在
```
shared/auth/
```
或
```
shared/api/
```
中。
不要滥用@x。这是最后的手段，不是推荐模式（见第7节）。
不要提取仅单个场景使用的代码。仅被一个页面使用的功能或实体应保留在该页面中。
不要使用按技术职责命名的文件。使用基于领域的命名（见规则4-4）。
谨慎在entities中添加UI。实体中的UI容易引发其他实体的跨导入。如果要在entities中添加UI段，仅允许从更高层级（features、widgets、pages）导入——绝不允许从其他实体导入。
不要创建“上帝切片”。职责过于宽泛的切片应拆分为专注的切片（例如，将
```
user-management/
```
拆分为
```
auth/
```
、
```
profile-edit/
```
、
```
password-reset/
```
）。

7. Cross-Import Resolution Order

7. 跨导入解决方案顺序

When two slices on the same layer need to share code, try these strategies in order. Always attempt earlier strategies first.

Merge slices — If two slices always change together, they likely belong in one slice.
Extract shared logic to entities — If multiple features/widgets share domain logic, move that logic to
```
entities/
```
. Keep UI in features/widgets.
Compose in a higher layer (IoC) — Use inversion of control. The parent layer (pages or app) imports both slices and connects them via render props, slots, or dependency injection.
@x notation (last resort) — Create explicit, controlled cross-imports between entities only. Document why other strategies do not apply. Review periodically.

For detailed code examples of each strategy, read

references/cross-import-patterns.md

当同一层级的两个切片需要共享代码时，请按顺序尝试以下策略。优先尝试前面的策略。

合并切片 — 如果两个切片总是一起变更，它们可能属于同一个切片。
将共享逻辑提取到entities — 如果多个功能/UI块共享领域逻辑，将该逻辑移至
```
entities/
```
。UI部分仍保留在features/widgets中。
在更高层级组合（控制反转） — 使用控制反转。父层级（pages或app）导入两个切片，并通过渲染属性、插槽或依赖注入将它们连接起来。
@x标记（最后的手段） — 仅在entities之间创建明确的、受控的跨导入。记录为何其他策略不适用。定期回顾。

每种策略的详细代码示例，请查看

references/cross-import-patterns.md

。

8. Segments & Structure Rules

8. 代码段与结构规则

Standard segments

标准代码段

Segments group code within a slice by technical purpose:

ui/
— UI components, styles, display-related code
model/
— Data models, state stores, business logic, validation
api/
— Backend integration, request functions, API-specific types
lib/
— Internal utility functions for this slice
config/
— Configuration, feature flags

代码段按技术用途对切片内的代码进行分组：

ui/
— UI组件、样式、与展示相关的代码
model/
— 数据模型、状态存储、业务逻辑、验证
api/
— 后端集成、请求函数、API专属类型
lib/
— 该切片专属的内部工具函数
config/
— 配置、功能开关

Layer structure rules

层级结构规则

App and Shared: No slices — organized directly by segments. Segments within these layers may import from each other.
Pages, Widgets, Features, Entities: Slices first, then segments inside each slice.

App和Shared：无切片——直接按代码段组织。这些层级内的代码段可以相互导入。
Pages、Widgets、Features、Entities：先按切片划分，每个切片内再按代码段组织。

File naming within segments

代码段内的文件命名

Always use domain-based names that describe what the code is about:

text

model/user.ts            ← User types + logic + store
model/order.ts           ← Order types + logic + store
api/fetch-profile.ts     ← Profile fetching
api/update-settings.ts   ← Settings update

If a segment has only one domain concern, the filename may match the slice name (e.g.,

features/auth/model/auth.ts

始终使用基于领域的名称，描述代码的用途：

text

model/user.ts            ← 用户类型+逻辑+存储
model/order.ts           ← 订单类型+逻辑+存储
api/fetch-profile.ts     ← 获取用户资料
api/update-settings.ts   ← 更新设置

如果一个代码段仅涉及一个领域关注点，文件名可以与切片名一致（例如，

features/auth/model/auth.ts

）。

9. Shared Layer Guide

9. Shared层级指南

Shared contains infrastructure with no business logic. It is organized by segments only (no slices). Segments within shared may import from each other.

Allowed in shared:

```
ui/
```
— UI kit (Button, Input, Modal, Card)
```
lib/
```
— Utilities (formatDate, debounce, classnames)
```
api/
```
— API client, route constants, CRUD helpers, base types
```
auth/
```
— Auth tokens, login utilities, session management
```
config/
```
— Environment variables, app settings
```
assets/
```
— Images, fonts, icons

Shared may contain application-aware code (route constants, API endpoints, branding assets, common types). It must never contain business logic, feature-specific code, or entity-specific code.

Shared层级包含无业务逻辑的基础设施。仅按代码段组织（无切片）。Shared内的代码段可以相互导入。

Shared中允许的内容：

```
ui/
```
— UI组件库（Button、Input、Modal、Card）
```
lib/
```
— 工具函数（formatDate、debounce、classnames）
```
api/
```
— API客户端、路由常量、CRUD助手、基础类型
```
auth/
```
— 认证令牌、登录工具、会话管理
```
config/
```
— 环境变量、应用设置
```
assets/
```
— 图片、字体、图标

Shared可以包含与应用相关的代码（路由常量、API端点、品牌资源、通用类型）。但绝对不能包含业务逻辑、功能专属代码或实体专属代码。

10. Quick Reference

10. 快速参考

Import direction:

app → pages → widgets → features → entities → shared

Minimal FSD:
```
app/
```
+
```
pages/
```
+
```
shared/
```
Create entities when: 2+ pages/features/widgets share the same business domain model, and the team agrees.
Create features when: 2+ pages/widgets share the same user interaction, and the team agrees.
Breaking rules: Only as an intentional design choice — document the reason, get team consensus.
Cross-import resolution: Merge → Extract to entities → Compose in higher layer → @x (last resort)
File naming: Domain-based (
```
user.ts
```
,
```
order.ts
```
). Never technical-role (
```
types.ts
```
,
```
utils.ts
```
).
Processes layer: Deprecated. See
```
references/migration-guide.md
```
.

导入方向：

app → pages → widgets → features → entities → shared

最小化FSD：
```
app/
```
+
```
pages/
```
+
```
shared/
```
创建entities的时机：2个及以上页面/功能/UI块共享相同的业务领域模型，且团队达成共识。
创建features的时机：2个及以上页面/UI块共享相同的用户交互，且团队达成共识。
打破规则：仅作为经过深思熟虑的设计选择——记录原因，获得团队共识。
跨导入解决方案：合并切片 → 提取到entities → 在更高层级组合 → @x（最后的手段）
文件命名：基于领域（
```
user.ts
```
、
```
order.ts
```
）。绝不要按技术职责命名（
```
types.ts
```
、
```
utils.ts
```
）。
Processes层级：已弃用。详情请查看
```
references/migration-guide.md
```
。

11. Conditional References

11. 条件参考文档

Read the following reference files only when the specific situation applies. Do not preload all references.

When creating, reviewing, or reorganizing folder and file structure for FSD layers and slices (e.g., "set up project structure", "where does this folder go"): → Read
```
references/layer-structure.md
```
When resolving cross-import issues between slices on the same layer, evaluating the @x pattern, or dealing with excessive entity coupling: → Read
```
references/cross-import-patterns.md
```
When migrating from FSD v2.0 to v2.1, converting a non-FSD codebase to FSD, or deprecating the processes layer: → Read
```
references/migration-guide.md
```
When integrating FSD with a specific framework (Next.js, Nuxt, Vite, CRA) or configuring path aliases: → Read
```
references/framework-integration.md
```
When implementing concrete code patterns for authentication, API request handling, type definitions, or state management (Redux, React Query) within FSD structure: → Read
```
references/practical-examples.md
```
Note: If you already loaded
```
layer-structure.md
```
in this conversation, avoid loading this file simultaneously. Address structure first, then load patterns in a follow-up step if needed.

仅在特定场景下才需要阅读以下参考文档。不要预先加载所有参考文档。

当创建、审查或重构FSD层级和切片的文件夹与文件结构时（例如，「设置项目结构」、「这个文件夹应该放在哪里」）： → 阅读
```
references/layer-structure.md
```
当解决同一层级切片间的跨导入问题、评估@x模式或处理过度的实体耦合时： → 阅读
```
references/cross-import-patterns.md
```
当从FSD v2.0迁移到v2.1、将非FSD代码库转换为FSD或弃用processes层级时： → 阅读
```
references/migration-guide.md
```
当将FSD与特定框架（Next.js、Nuxt、Vite、CRA）集成或配置路径别名时： → 阅读
```
references/framework-integration.md
```
当在FSD结构内实现认证、API请求处理、类型定义或状态管理（Redux、React Query）等具体代码模式时： → 阅读
```
references/practical-examples.md
```
注意：如果在本次对话中已加载
```
layer-structure.md
```
，请避免同时加载此文档。先处理结构问题，若需要再在后续步骤中加载模式文档。

feature-sliced-design

Original

Translation

Feature-Sliced Design (FSD) v2.1

Feature-Sliced Design (FSD) v2.1

1. Core Philosophy & Layer Overview

1. 核心理念与层级概述

2. Decision Framework

2. 决策框架

3. Quick Placement Table

3. 快速放置对照表

4. Architectural Rules (MUST)

4. 架构规则（必须遵守）

4-1. Import only from lower layers

4-1. 仅从更低层级导入代码

4-2. Public API — every slice exports through index.ts

4-2. 公共API — 每个切片仅通过index.ts导出

4-3. No cross-imports between slices on the same layer

4-3. 禁止同一层级内切片间的跨导入

4-4. Domain-based file naming (no desegmentation)

4-4. 基于领域的文件命名（避免按技术职责拆分）

4-5. No business logic in shared/

4-5. shared/目录中禁止包含业务逻辑

5. Recommendations (SHOULD)

5. 推荐实践（建议遵守）

5-1. Pages First — place code where it is used

5-1. 页面优先 — 代码放在使用它的位置

5-2. Be conservative with entities

5-2. 谨慎使用entities层级

5-3. Start with minimal layers

5-3. 从最小化层级开始

5-4. Validate with the Steiger linter

5-4. 使用Steiger代码检查器验证

6. Anti-patterns (AVOID)

6. 反模式（避免使用）

7. Cross-Import Resolution Order

7. 跨导入解决方案顺序

8. Segments & Structure Rules

8. 代码段与结构规则

Standard segments

标准代码段

Layer structure rules

层级结构规则

File naming within segments

代码段内的文件命名

9. Shared Layer Guide

9. Shared层级指南

10. Quick Reference

10. 快速参考

11. Conditional References

11. 条件参考文档

4-5.
`shared/`
目录中禁止包含业务逻辑