框架设计指南：构建可复用.NET库的约定、惯例与模式（第3版）

本书从最基本的设计原则和准则出发，全方位介绍了设计框架的很好实践，是微软工程师从.NET Framework开发伊始到现如今的.NET这二十来年间宝贵经验的总结。

与第2版发布时的2008年相比，今天的软件开发范式用翻天覆地来形容也不为过，容器化、云服务、跨平台、DevOps等，都对今天的软件开发者和框架设计者提出了更高的要求。本书对第2版的内容进行了全面的更新，以适应当下发展的潮流。

本书虽然是面向.NET平台上的框架设计的，但对其他平台的框架设计同样具有非凡的借鉴价值。通过阅读本书，读者可以了解到如何设计出一个对使用者而言简单、易用且具有一致性的优秀框架。

Krzysztof Cwalina 是微软的软件架构师，是 .NET框架团队的初始成员之一，在职业生涯中，他成功设计了许多 .NET API。目前，他正致力于帮助微软的不同团队开发不同编程语言下的可复用 API。Krzysztof 拥有爱荷华大学计算机科学专业的学士学位和硕士学位。

Jeremy Barton 是 .NET Core Libraries 团队的一名工程师。在使用 C# 设计和开发小型框架十几年后，他于 2015 年加入 .NET 团队，从事全新的 .NET Core 项目中密码学相关类库的跨平台开发工作。Jeremy 毕业于罗斯-霍曼理工学院计算机科学和数学专业。

Brad Abrams 是微软通用语言运行时（Common Language Runtime，CLR）和 .NET 框架团队的初始成员之一。从 1998 年开始，他就一直在为 .NET 框架做设计。Brad 从构建基类库（BCL）开始他的框架设计生涯，而这个库后来成为 .NET框架的核心部分。此外，他还是通用语言规范（Common Language Specification，CLS）、.NET框架设计指南和.NET框架中ECMA/ISO通用语言基础架构（Common Language Infrastructure，CLI）标准实现的主要作者。Brad 编写和合著了多本出版物，包括Programming in the .NET Environment和.NET Framework Standard Library Annotated Reference的卷一和卷二。Brad 毕业于北卡罗来纳州立大学计算机科学专业，你可以在他的博客上了解他最近的想法。Brad现在是Google的集团产品经理（Group Product Manager），他正在为 Google Assistant孵化新项目。

译者简介

王桥，2016年毕业于厦门大学，现在是微软的软件开发工程师。他在大学毕业后就一直深耕于 Web开发领域，在 TypeScript/JavaScript 和 . NET 等方面有丰富的编程实战经验。

（1）从“要做”和“不要做”两个视角彼此推翻和对抗，推演规范形成的终极思辨逻辑。

（2）针对语言构成剖析编码规范, 提供一种上手一门新语言快速登堂入室的新思路。

（3）被誉为C# 世界的《Effective C++》，各路大神精彩点评是这本书的点睛之笔。

（4）广泛流传这样一句话：. NET程序员如一生只读三本书，这本书必定赫然在列。

在设计 .NET 平台之初，我们希望它能成为当时最具生产力的企业应用开发平台。在 20 年前，这意味着将“客服端-服务端”架构的应用托管在专用硬件之上。

今天，我们发现自己正置身于行业最大的范式转移之一中：转向云计算。这一转变为企业带来了新的机遇，但对现有的平台来说可能会很棘手，因为开发人员想要开发新型应用程序，导致现有的平台需要去适应由此而来的各种各样的需求。

.NET平台转型相当成功，我认为其中一个主要原因是，我们在设计它的过程中非常小心谨慎，不仅关注生产力、一致性和简单性，还注重确保它能够随着时间的推移不断发展。.NET Core正代表了这种进化，它在云应用开发人员所关心的诸如性能、资源利用率和容器化支持等方面都有显著的提升。

《框架设计指南》第3版新增了许多设计准则，这些准则与 .NET 团队在从“客服端-服务端”应用到云应用这一转变过程中所采取的一系列变更息息相关。

Scott Guthrie

雷德蒙，华盛顿

2020年1月

导论 1
1．1 设计精良的框架的特质 2
1．1．1 设计精良的框架是简单的 2
1．1．2 设计精良的框架设计成本高昂 3
1．1．3 设计精良的框架充满权衡 4
1．1．4 设计精良的框架会借鉴过往经验 5
1．1．5 设计精良的框架旨在不断发展 5
1．1．6 设计精良的框架是完整统一的 6
1．1．7 设计精良的框架是一致的 6
2 框架设计基础 7
2．1 渐进式框架 9
2．2 框架设计基本原则 12
2．2．1 场景驱动设计原则 12
2．2．2 低门槛原则 18
2．2．3 对象模型自文档化原则 22
2．2．4 分层架构原则 27
总结 29
3 命名准则 30
3．1 大小写约定 30
3．1．1 标识符的大小写规则 31
3．1．2 大写首字母缩写词 33
3．1．3 大写复合词和常见术语 36
3．1．4 大小写敏感 38
3．2 通用命名约定 38
3．2．1 词汇选择 39
3．2．2 使用简写和首字母缩写词 41
3．2．3 避免使用特定于编程语言的名称 41
3．2．4 命名现有 API 的新版本 43
3．3 程序集、DLL 和包的命名 45
3．4 命名空间的命名 47
3．4．1 命名空间和类型名称的冲突 48
3．5 类、结构体和接口的命名 50
3．5．1 泛型参数的命名 52
3．5．2 通用类型的命名 52
3．5．3 枚举的命名 53
3．6 类型成员的命名 55
3．6．1 方法的命名 55
3．6．2 属性的命名 55
3．6．3 事件的命名 57
3．6．4 字段的命名 58
3．7 命名参数 59
3．7．1 命名运算符重载参数 59
3．8 命名资源 60
总结 60
4 类型设计准则 61
4．1 类型和命名空间 63
4．2 在类和结构体之间选择 66
4．3 在类和接口之间选择 68
4．4 抽象类设计 75
4．5 静态类设计 76
4．6 接口设计 77
4．7 结构体设计 79
4．8 枚举设计 83
4．8．1 设计标记枚举 89
4．8．2 添加枚举值 92
4．9 嵌套类型 93
4．10 类型和程序集元数据 95
4．11 强类型字符串 97
总结 100
5 成员设计 101
5．1 一般成员设计准则 101
5．1．1 成员重载 101
5．1．2 显式实现接口成员 111
5．1．3 在属性和方法之间选择 114
5．2 属性设计 119
5．2．1 索引属性设计 120
5．2．2 属性变更通知事件 123
5．3 构造函数设计 124
5．3．1 类型构造函数准则 130
5．4 事件设计 132
5．5 字段设计 136
5．6 扩展方法 139
5．7 运算符重载 146
5．7．1 重载 operator== 149
5．7．2 转换运算符 149
5．7．3 比较运算符 151
5．8 参数设计 152
5．8．1 在枚举参数和布尔参数之间选择 154
5．8．2 参数验证 156
5．8．3 参数传递 159
5．8．4 参数数量可变的成员 162
5．8．5 指针参数 165
5．9 在成员签名中使用元组 166
总结 171
6 可扩展性设计 172
6．1 可扩展性机制 172
6．1．1 非密封类 172
6．1．2 受保护的成员 174
6．1．3 事件和回调 175
6．1．4 虚成员 180
6．1．5 抽象（抽象类和接口） 181
6．2 基类 183
6．3 密封 185
总结 187
7 异常 188
7．1 抛出异常 192
7．2 选择抛出正确的异常类型 196
7．2．1 错误消息设计 199
7．2．2 异常处理 200
7．2．3 包装异常 205
7．3 使用标准异常类型 206
7．3．1 Exception和SystemException 206
7．3．2 ApplicationException 207
7．3．3 InvalidOperationException 207
7．3．4 ArgumentException、ArgumentNullException 和 ArgumentOutOfRangeException 207
7．3．5 NullReferenceException、IndexOutOfRangeException 和 AccessViolationException 208
7．3．6 StackOverflowException 208
7．3．7 OutOfMemoryException 209
7．3．8 ComException、SEHException和ExecutionEngineException 210
7．3．9 OperationCanceledException 和 TaskCanceledException 210
7．3．10 FormatException 210
7．3．11 PlatformNotSupportedException 211
7．4 设计自定义异常 211
7．5 异常和性能 212
7．5．1 测试者-执行者模式 212
7．5．2 Try模式 213
总结 216
8 使用准则 217
8．1 数组 217
8．2 特性 220
8．3 集合 223
8．3．1 集合参数 224
8．3．2 集合属性和返回值 225
8．3．3 在数组和集合之间选择 229
8．3．4 实现自定义集合 230
8．4 DateTime 和 DateTimeOffset 231
8．5 ICloneable 233
8．6 IComparable＜T＞ 和 IEquatable＜T＞ 234
8．7 IDisposable 236
8．8 Nullable＜T＞ 236
8．9 Object 237
8．9．1 Object．Equals 237
8．9．2 Object．GetHashCode 238
8．9．3 Object．ToString 240
8．10 序列化 241
8．11 Uri 243
8．11．1 System．Uri 的实现准则 244
8．12 System．Xml 的使用 245
8．13 相等运算符 246
8．13．1 值类型上的相等运算符 248
8．13．2 引用类型上的相等运算符 248
9 通用设计模式 249
9．1 聚合组件 249
9．1．1 面向组件的设计 251
9．1．2 因子类型 253
9．1．3 聚合组件准则 254
9．2 异步模式 256
9．2．1 选择异步模式 256
9．2．2 基于任务的异步模式 258
9．2．3 异步方法的返回类型 263
9．2．4 为现有的同步方法制作一个异步变体 265
9．2．5 异步模式一致性的实现准则 268
9．2．6 经典异步模式 272
9．2．7 基于事件的异步模式 273
9．2．8 IAsyncDisposable 273
9．2．9 IAsyncEnumerable＜T＞ 273
9．2．10 await foreach 的使用准则 274
9．3 依赖属性 276
9．3．1 依赖属性设计 277
9．3．2 附加属性的设计 279
9．3．3 依赖属性校验 280
9．3．4 依赖属性变更通知 280
9．3．5 依赖属性中的值强制 281
9．4 Dispose 模式 282
9．4．1 基本Dispose模式 284
9．4．2 可终结类型 290
9．4．3 限定作用域的操作 293
9．4．4 IAsyncDisposable 296
9．5 工厂 299
9．6 LINQ 支持 303
9．6．1 LINQ 概览 303
9．6．2 实现 LINQ 支持的方法 304
9．7 可选功能模式 309
9．8 协变和逆变 312
9．8．1 逆变 315
9．8．2 协变 316
9．8．3 模拟协变模式 319
9．9 模板方法 321
9．10 超时 323
9．11 XAML 可读类型 324
9．12 操作缓冲 326
9．12．1 数据转换操作 338
9．12．2 向缓冲区中写入固定大小或预定大小的数据 343
9．12．3 使用 Try-Write 模式向缓冲区中写入数据 344
9．12．4 部分写入缓冲区和OperationStatus 348
9．13 最后 353
附录A C#编码风格约定 354
A．1 通用风格约定 355
A．1．1 花括号的使用 355
A．1．2 空格的使用 357
A．1．3 缩进的使用 358
A．1．4 垂直空白 360
A．1．5 成员修饰符 361
A．1．6 其他 362
A．2 命名约定 367
A．3 注释 368
A．4 文件组织 369
附录B 过时的准则 371
B．3 命名准则中的过时准则 371
B．3．8 命名资源 371
B．4 类型设计准则中的过时准则 372
B．4．1 类型和命名空间 372
B．5 成员设计准则中的过时准则 374
B．5．4 事件的设计 374
B．7 异常设计准则中的过时准则 375
B．7．4 设计自定义异常 375
B．8 常见类型使用准则中的过时准则 376
B．8．10 序列化 376
B．9 通用设计模式中的过时准则 383
B．9．2 异步模式 383
B．9．4 Dispose 模式 394
附录C API规范示例 398
附录D 不兼容变更 403
D．1 修改程序集 404
D．1．1 改变程序集的名称（） 404
D．2 添加命名空间 405
D．2．1 添加与现有类型冲突的命名空间（） 405
D．3 修改命名空间 405
D．3．1 修改命名空间的名称或改变大小写（） 405
D．4 移动类型 405
D．4．1 通过 [TypeForwardedTo] 移动类型（） 405
D．4．2 不通过 [TypeForwardedTo] 移动类型（） 406
D．5 删除类型 406
D．5．1 删除类型（） 406
D．6 修改类型 407
D．6．1 密封一个非密封的类型（） 407
D．6．2 解封一个密封类型（） 407
D．6．3 改变类型名称的大小写（） 407
D．6．4 改变类型名称（） 407
D．6．5 改变类型的命名空间（） 408
D．6．6 为结构体添加 readonly 修饰符（） 408
D．6．7 从结构体中移除 readonly 修饰符（） 408
D．6．8 为现有接口添加基接口（） 408
D．6．9 为同一个泛型接口添加第二个声明（） 409
D．6．10 将类变更为结构体（） 409
D．6．11 将结构体变更为类（） 410
D．6．12 将 struct 变更为 ref struct（） 410
D．6．13 将 ref struct 变更为（非ref）struct（） 410
D．7 添加成员 411
D．7．1 通过 new 修饰符掩盖基类成员（） 411
D．7．2 添加抽象成员（） 411
D．7．3 为非密封类型添加成员（） 411
D．7．4 为非密封类型添加覆写成员（） 412
D．7．5 为结构体添加第一个引用类型字段（） 412
D．7．6 为接口添加成员（） 412
D．8 移动成员 413
D．8．1 将成员移动到基类中（） 413
D．8．2 将成员移动到基接口中（） 413
D．8．3 将成员移动到派生类型中（） 413
D．9 删除成员 413
D．9．1 从非密封类型中删除终结器（） 413
D．9．2 从密封类型中删除终结器（） 414
D．9．3 删除非覆写成员（） 414
D．9．4 删除虚拟成员的override（） 414
D．9．5 删除抽象成员的override（） 414
D．9．6 删除或重命名可序列化类型的私有字段（?） 415
D．10 重载成员 415
D．10．1 为成员添加第一个重载（） 415
D．10．2 为引用类型参数添加可选参数重载（?） 416
D．11 更改成员签名 416
D．11．1 重命名方法的参数（） 416
D．11．2 添加或删除方法的参数（） 416
D．11．3 改变方法参数的类型（） 417
D．11．4 重新排列具有不同类型的方法参数（） 417
D．11．5 重新排列具有相同类型的方法参数（） 417
D．11．6 改变方法的返回类型（） 418
D．11．7 改变属性的类型（） 418
D．11．8 将成员的可见性从 public 变更为其他的可见性（） 418
D．11．9 将成员的可见性从 protected 变更为 public（） 419
D．11．10 将虚（或抽象）成员从 protected 变更为 public（） 419
D．11．11 添加或删除 static 修饰符（） 419
D．11．12 改为（或不再）按引用传递参数（） 419
D．11．13 改变按引用传递参数的风格（） 420
D．11．14 为结构体的方法添加 readonly 修饰符（） 420
D．11．15 从结构体的方法中删除 readonly 修饰符（） 420
D．11．16 将必需参数变更为可选参数（） 421
D．11．17 将可选参数变更为必需参数（?） 421
D．11．18 改变可选参数的默认值（） 421
D．11．19 改变常量字段的值（） 421
D．11．20 将抽象成员变更为虚成员（） 422
D．11．21 将虚成员变更为抽象成员（） 422
D．11．22 将非虚成员变更为虚成员（） 422
D．12 改变行为 423
D．12．1 将运行时错误异常变更为使用错误异常（） 423
D．12．2 将使用错误异常变更为有用的行为（） 423
D．12．3 改变方法返回值的类型（?） 423
D．12．4 抛出新的异常类型（） 424
D．12．5 抛出新的异常类型，且它是从现有的异常类型中派生的（） 424
D．13 最后 424