读 Angular 代码风格指南

Angular 代码风格指南（精华版）

原文参考：Angular 官方文档

Angular 的代码风格指南非常全面，但其中有不少原则其实与框架无关、对所有前端项目都适用。本文只保留最核心、最具长期价值的部分，帮助你写出更易读、更易维护、更易协作的代码。

---

一、单一职责（Single Responsibility）

一个文件，只做一件事。

• 每个文件只定义一个概念（组件 / 服务 / 指令等）
• 文件大小建议控制在 400 行以内
• 函数尽量保持简单，不超过 75 行

为什么？

• 小文件更容易阅读、维护和测试
• 降低团队协作中的冲突概率
• 避免隐式共享状态、意外闭包和非预期耦合

单一职责不是形式主义，而是让代码更安全、更可复用的基础。

---

二、命名：让代码自己“说话”

代码被人阅读的时间，远远多于被机器执行的时间。

命名的两个基本原则

1. 统一规则：整个项目使用一致的命名方式
2. 统一模式：名称能同时表达“它是什么”和“它做什么”

文件命名

Angular 推荐：

• 横杠（-）：分隔描述性单词
• 点（.）：分隔特性名与类型

统一格式：

feature.type.ts

示例：

• hero.service.ts
• home.component.ts
• app.module.ts
• global.styles.css

常见类型后缀：

• .component
• .service
• .pipe
• .directive
• .module

类型后缀可以扩展，但不要泛滥，否则会降低可读性。

文件名与符号名一致

文件名和导出的类名必须一一对应：

• hero.service.ts → HeroService
• todo-list.component.ts → TodoListComponent

规则很简单：

• 类名使用 PascalCase
• 类名 = 文件名（去掉分隔符）+ 类型后缀

单元测试文件命名

测试文件与源文件保持一致：

xxx.ts        → xxx.spec.ts

这样可以快速定位和自动匹配测试。

---

三、结构组织与 LIFT 原则

一个好的项目结构，应该让你几乎不用思考就能找到代码。

Angular 推荐使用 LIFT 原则（重要性依次递减）：

• Locate：快速定位
• Identify：一眼识别
• Flattest：尽量扁平
• Try DRY：尝试不重复

判断结构是否合理的标准只有一个：

“我能否快速打开与这个特性相关的所有文件并开始工作？”

Locate（快速定位）

• 相关文件放在一起
• 目录结构直观、可预期
• 即使不知道文件名，也能靠位置找到

清晰的结构，是效率最高的“搜索引擎”。

Identify（一眼识别）

文件名应做到：看到名字就知道里面有什么。

• 一个文件只包含一个组件 / 服务
• 使用完整、清晰的名字，而不是模糊缩写

宁可文件名长一点，也不要让读代码的人去猜。

Flattest（尽量扁平）

• 优先使用扁平结构，方便搜索
• 当同一目录文件数达到 7–10 个 时，再考虑拆分子目录
• 避免超过 7 层的目录深度

没有人愿意在“迷宫”里找代码。

Try DRY（尝试不重复）

• 遵循 DRY（Don’t Repeat Yourself）
• 但不要为了 DRY 牺牲可读性和结构清晰度

如果 DRY 与 LIFT 冲突，优先 LIFT。

---

四、推荐的目录约定

• 所有源码统一放在 src 目录下
• 一个组件如果有多个伴生文件（.ts / .html / .css / .spec），就放在同一个文件夹

示例结构：

src
├─ app
│  ├─ moduleA
│  │  ├─ components
│  │  ├─ assets
│  │  └─ ...
│  ├─ moduleB
│  └─ shared
├─ layouts
├─ assets
├─ main.ts
└─ ...

---

总结

Angular 风格指南的核心并不在 Angular 本身，而在于：

• 单一职责：控制复杂度
• 清晰命名：降低认知成本
• 合理结构：提升协作效率

这些原则放在任何前端项目里，都同样成立。