211 lines
5.6 KiB
Markdown
211 lines
5.6 KiB
Markdown
# FSD前端架构设计技能
|
||
|
||
`前端架构` `Feature-Sliced Design` `Codex` `React` `代码组织`
|
||
|
||
# Codex 的 Feature-Sliced Design 技能（v2.1）
|
||
|
||
本技能帮助 Codex 将 Feature-Sliced Design（FSD）v2.1 架构方法论应用于前端项目。
|
||
|
||
## v2.1 新增内容
|
||
|
||
**核心更新**：**"页面优先"**方法。
|
||
|
||
- 在需要复用之前，将代码保留在使用它的地方。
|
||
- 从 `pages` 和 `widgets` 开始；仅在真正复用时才提取到 `features` 或 `entities`。
|
||
- 提升内聚性，简化重构，加快开发速度。
|
||
|
||
## 本技能包含的内容
|
||
|
||
- 6 个活跃 FSD 层（`app`、`pages`、`widgets`、`features`、`entities`、`shared`）的完整指南
|
||
- **v2.1 新增**："页面优先"代码放置策略
|
||
- **v2.1 新增**：实体间跨导入的公共 API（`@x` 符号）
|
||
- **v2.1 新增**：`shared` 中感知应用的代码
|
||
- 层/切片/片段的组织规则
|
||
- 公共 API 模式与最佳实践
|
||
- React、Redux、React Query 和 Next.js 示例
|
||
- 需要避免的反模式（包括过早提取）
|
||
- 从 v2.0 迁移到 v2.1 的策略
|
||
- 正确放置代码的决策框架
|
||
- Steiger 架构 lint 工具集成
|
||
|
||
## 安装
|
||
|
||
### 为 Codex 本地安装
|
||
|
||
1. 创建自定义技能目录：
|
||
```bash
|
||
mkdir -p ~/.codex/skills
|
||
```
|
||
|
||
2. 复制为单个技能文件：
|
||
```bash
|
||
cp SKILL.md ~/.codex/skills/feature-sliced-design.md
|
||
```
|
||
|
||
3. 或复制为技能文件夹：
|
||
```bash
|
||
mkdir -p ~/.codex/skills/feature-sliced-design
|
||
cp SKILL.md ~/.codex/skills/feature-sliced-design/
|
||
cp -r agents ~/.codex/skills/feature-sliced-design/
|
||
```
|
||
|
||
### 替代方法
|
||
|
||
将 `feature-sliced-design-skill` 文件夹放置在项目根目录，并指定 Codex 使用它。
|
||
|
||
## 使用方式
|
||
|
||
在以下情况下，该技能将自动触发：
|
||
|
||
- 提及"FSD"、"Feature-Sliced Design"或"feature sliced"
|
||
- 创建新的前端结构
|
||
- 重构现有代码
|
||
- 讨论架构或代码组织方式
|
||
- 询问某段代码应该放在哪里
|
||
- 解决跨导入或依赖问题
|
||
- 拆解功能或组件
|
||
|
||
## 使用示例
|
||
|
||
### 示例 1：创建新功能（v2.1 方式）
|
||
```
|
||
用户："创建一个个人资料编辑表单"
|
||
Codex：我将把它放在 pages/profile/，因为它只在这个页面使用。
|
||
如果之后需要复用，我们可以将其移动到 features/。
|
||
```
|
||
|
||
### 示例 2：使用页面优先方式重构
|
||
```
|
||
用户："我在 features/ 中有一个 UserProfile 组件，但它只在一个页面上使用"
|
||
Codex：在 v2.1 中，它应该移回 pages/。features 应包含可复用的交互逻辑。
|
||
```
|
||
|
||
### 示例 3：项目初始化
|
||
```
|
||
用户："帮我搭建一个使用 FSD v2.1 的新 React 项目"
|
||
Codex：[创建结构、配置路径别名、解释页面优先原则]
|
||
```
|
||
|
||
### 示例 4：跨导入
|
||
```
|
||
用户："实体 User 需要引用 Order"
|
||
Codex：使用 @x 符号在实体之间进行显式跨导入。
|
||
```
|
||
|
||
## v2.1 核心概念
|
||
|
||
### 页面优先方法
|
||
```
|
||
1. 从 pages/ 开始，将代码保留在使用它的位置附近。
|
||
2. 仅在真正复用时才提取到 features/entities。
|
||
3. 不要预测未来的复用需求；等待真实的重复出现。
|
||
```
|
||
|
||
### 层结构
|
||
```
|
||
app/ <- 应用初始化
|
||
pages/ <- 包含自身逻辑的页面
|
||
widgets/ <- 包含自身逻辑的复合 UI 块
|
||
features/ <- 可复用的业务交互
|
||
entities/ <- 可复用的业务实体
|
||
shared/ <- 基础设施与感知应用的共享代码
|
||
```
|
||
|
||
**注意**：`processes/` 层在 v2.1 中已废弃。
|
||
|
||
### 导入规则
|
||
模块只能从更低层级导入：
|
||
- `features/` -> `entities/`、`shared/`
|
||
- `entities/` 不得从 `features/` 导入
|
||
|
||
### 公共 API
|
||
每个切片应通过 `index.ts` 暴露公共 API：
|
||
```typescript
|
||
// features/auth/index.ts
|
||
export { LoginForm } from './ui/LoginForm';
|
||
export { useAuth } from './model/useAuth';
|
||
```
|
||
|
||
## 典型项目结构
|
||
|
||
```text
|
||
src/
|
||
├── app/
|
||
├── pages/
|
||
├── widgets/
|
||
├── features/
|
||
├── entities/
|
||
└── shared/
|
||
```
|
||
|
||
## 支持的技术栈
|
||
|
||
- React
|
||
- Vue
|
||
- Angular
|
||
- Svelte
|
||
- Next.js
|
||
- Redux / Redux Toolkit
|
||
- React Query
|
||
- MobX
|
||
- TypeScript
|
||
- Vite
|
||
- Create React App
|
||
|
||
## 附加工具
|
||
|
||
### Steiger——FSD 架构 lint 工具
|
||
|
||
[Steiger](https://github.com/feature-sliced/steiger) 是验证 FSD 规则的官方工具：
|
||
|
||
```bash
|
||
npm install -D @feature-sliced/steiger
|
||
npx steiger src
|
||
```
|
||
|
||
检查内容包括：
|
||
- 导入规则违反
|
||
- 公共 API 使用情况
|
||
- 跨导入违规
|
||
- 层结构一致性
|
||
|
||
## 资源
|
||
|
||
- [FSD 官方文档](https://feature-sliced.design/)
|
||
- [FSD 文档仓库](https://github.com/feature-sliced/documentation)
|
||
- [Steiger lint 工具](https://github.com/feature-sliced/steiger)
|
||
- [FSD 示例](https://feature-sliced.design/examples)
|
||
|
||
## 从 FSD v2.0 迁移到 v2.1
|
||
|
||
迁移是非破坏性的，可以逐步进行：
|
||
|
||
1. 审查现有代码。
|
||
2. 将页面专属逻辑移回 `pages/`。
|
||
3. 将 widget 专属逻辑保留在 `widgets/`。
|
||
4. 在 `features/` 和 `entities/` 中只保留真正可复用的逻辑。
|
||
5. 在 `shared` 中更新基础设施和应用级常量。
|
||
6. 移除已废弃的 `processes/` 用法。
|
||
|
||
## 故障排查
|
||
|
||
### 技能未激活
|
||
- 确认文件/文件夹位于预期的技能目录中。
|
||
- 确认命名正确。
|
||
- 重启 Codex。
|
||
|
||
### 不确定代码应放在哪里
|
||
询问 Codex："在 FSD 中，[代码描述] 应该放在哪里？"
|
||
|
||
### 导入规则违反
|
||
该技能应能识别违规并提出修复方案。
|
||
|
||
## 许可证
|
||
|
||
本技能基于 Feature-Sliced Design 官方文档，可自由使用。
|
||
|
||
---
|
||
|
||
**重要**：本技能遵循 FSD v2.1 和"页面优先"方法。请将其视为实用指南，而非一成不变的规则。
|
||
|
||
**黄金法则（v2.1）**：从 `pages/widgets` 开始；仅当真正的复用需求出现时，才提取到 `features/entities`。 |