From 32eda66409a530646b7ff4040c7b48640fc411f7 Mon Sep 17 00:00:00 2001 From: "binpeng.liu" Date: Tue, 31 Oct 2023 15:17:07 +0800 Subject: [PATCH] feature: design patter --- Chapter1 - iOS/1.110.md | 33 +- Chapter1 - iOS/1.48.md | 8 +- Chapter6 - Design Pattern/6.10.md | 314 ++++++++++++++ Chapter6 - Design Pattern/6.11.md | 193 +++++++++ Chapter6 - Design Pattern/6.12.md | 37 ++ Chapter6 - Design Pattern/6.13.md | 178 ++++++++ Chapter6 - Design Pattern/6.14.md | 89 ++++ Chapter6 - Design Pattern/6.15.md | 42 ++ Chapter6 - Design Pattern/6.16.md | 239 +++++++++++ Chapter6 - Design Pattern/6.17.md | 58 +++ Chapter6 - Design Pattern/6.18.md | 172 ++++++++ Chapter6 - Design Pattern/6.19.md | 223 ++++++++++ Chapter6 - Design Pattern/6.2.md | 162 ++++++++ Chapter6 - Design Pattern/6.20.md | 486 ++++++++++++++++++++++ Chapter6 - Design Pattern/6.21.md | 208 +++++++++ Chapter6 - Design Pattern/6.22.md | 384 +++++++++++++++++ Chapter6 - Design Pattern/6.23.md | 171 ++++++++ Chapter6 - Design Pattern/6.3.md | 106 +++++ Chapter6 - Design Pattern/6.4.md | 224 ++++++++++ Chapter6 - Design Pattern/6.5.md | 96 +++++ Chapter6 - Design Pattern/6.6.md | 58 +++ Chapter6 - Design Pattern/6.7.md | 7 + Chapter6 - Design Pattern/6.8.md | 82 ++++ Chapter6 - Design Pattern/6.9.md | 209 ++++++++++ Chapter6 - Design Pattern/chapter6.md | 24 ++ SUMMARY.md | 22 + assets/EventBus-ObserverRegisterTable.png | Bin 0 -> 59681 bytes assets/EventBus-Post.png | Bin 0 -> 40834 bytes assets/oop-mixBetterThanSuper.png | Bin 0 -> 57896 bytes 29 files changed, 3809 insertions(+), 16 deletions(-) create mode 100644 Chapter6 - Design Pattern/6.10.md create mode 100644 Chapter6 - Design Pattern/6.11.md create mode 100644 Chapter6 - Design Pattern/6.12.md create mode 100644 Chapter6 - Design Pattern/6.13.md create mode 100644 Chapter6 - Design Pattern/6.14.md create mode 100644 Chapter6 - Design Pattern/6.15.md create mode 100644 Chapter6 - Design Pattern/6.16.md create mode 100644 Chapter6 - Design Pattern/6.17.md create mode 100644 Chapter6 - Design Pattern/6.18.md create mode 100644 Chapter6 - Design Pattern/6.19.md create mode 100644 Chapter6 - Design Pattern/6.2.md create mode 100644 Chapter6 - Design Pattern/6.20.md create mode 100644 Chapter6 - Design Pattern/6.21.md create mode 100644 Chapter6 - Design Pattern/6.22.md create mode 100644 Chapter6 - Design Pattern/6.23.md create mode 100644 Chapter6 - Design Pattern/6.3.md create mode 100644 Chapter6 - Design Pattern/6.4.md create mode 100644 Chapter6 - Design Pattern/6.5.md create mode 100644 Chapter6 - Design Pattern/6.6.md create mode 100644 Chapter6 - Design Pattern/6.7.md create mode 100644 Chapter6 - Design Pattern/6.8.md create mode 100644 Chapter6 - Design Pattern/6.9.md create mode 100644 assets/EventBus-ObserverRegisterTable.png create mode 100644 assets/EventBus-Post.png create mode 100644 assets/oop-mixBetterThanSuper.png diff --git a/Chapter1 - iOS/1.110.md b/Chapter1 - iOS/1.110.md index f8be542..7317cb8 100644 --- a/Chapter1 - iOS/1.110.md +++ b/Chapter1 - iOS/1.110.md @@ -1,19 +1,21 @@ ## 妙用设计模式来设计一个客户端校验器 -> 订单在提交的时候会面临不同的校验规则，不同的校验规则会有不同的处理。假设这个处理就是弹窗。 -> -> 有的时候会命中规则1，则弹窗1，有的时候同时命中规则1、2、3，但由于存在规则的优先级，则会处理优先级最高的弹窗1。 -> -> 老的业务背景下，弹窗优先级或者说校验规则是统一的。直接用函数翻译实现，写多个 if 问题不大。 -> -> 但在新业务背景下，不同的条件，弹窗优先级不一致，之前的写法需要写大量的嵌套判断，代码难以维护。 -> -> 所以问题抽象为：如何设计一个校验器 +> 业务逻辑千变万化，弹窗优先级不断改变，代码冗余问题和难以维护问题如何解决？ +> 本篇文章从设计模式角度出发，讨论责任链设计模式和工厂设计模式2个方式，如何去设计一个校验器，同时解决代码冗余和难以维护的问题 ## 问题背景 +订单在提交的时候会面临不同的校验规则，不同的校验规则会有不同的处理。假设这个处理就是弹窗。 +有的时候会命中规则1，则弹窗1，有的时候同时命中规则1、2、3，但由于存在规则的优先级，则会处理优先级最高的弹窗1。 + +老的业务背景下，弹窗优先级或者说校验规则是统一的。直接用函数翻译实现，写多个 if 问题不大。 +但在新业务背景下，不同的条件，弹窗优先级不一致，之前的写法需要写大量的嵌套判断，代码难以维护。 + +所以问题抽象为：如何设计一个校验器 + + 为了清晰说明问题，假设线上的弹窗校验规则为：A -> B -> C ```Plain @@ -193,7 +195,7 @@ Node 洋葱模式：发送一个 Request 一层层中间件去处理，比如添 采用责任链设计模式。基类 `OrderSubmitBaseValidator` 声明接口，是一个抽象类： - 有一个属性 `nextValidator` 用于指向下一个校验器 -- 有一个方法 `- (void)validate:(id)params;` 用于处理校验，内部默认实现是传递给下一个校验器。 +- 有一个方法 `- (void)validate:(id)params;` 用于处理校验，内部利用模版模式，默认实现是传递给下一个校验器 ```Shell //.h @@ -294,7 +296,7 @@ let validateType = [OrderSubmitValidator generateTypeWithParams:params]; [OrderSubmitValidator validateWith:validateType]; ``` -`validateWith` 方法内部根据 validateType 去组装 Map 的 key，然后从 Map 中取出具体规则组合，然后依次迭代遍历执行 +利用策略模式 `validateWith` 方法内部根据 validateType 去组装 Map 的 key，然后从 Map 中取出具体规则组合，然后依次迭代遍历执行 ``` let rulesMap = { @@ -303,13 +305,16 @@ let rulesMap = { !isVIP: [a-c-d-b], } ``` +这部分策略的生成也可以单独抽取出去，比如 ValidateStrategyFactory 去根据不同的信息，生成不同的策略。 优点： 1. 解决了现在的错误弹窗的隐含逻辑，后续人接手，弹窗优先级清晰可见，提高可维护性，减少出错概率 -2. 对于判断（校验）的增减都无需关心其他的校验规则。类似维护链表，仅在一开始指定即可，符合“开闭原则 +2. 对于判断（校验）的增减都无需关心其他的校验规则。类似维护链表，仅在一开始指定即可，符合“开闭原则” 3. 对于现有校验规则的修改足够收口，每个规则都有自己的 validator 和 validate 方法 -4. 目前弹窗优先级针对 EVA 、BTC 存在不同优先级顺序，如果按照现有的方案实施，则会存在很多冗余代码 +4. 目前弹窗优先级针对 isVIP、isCharged 存在不同优先级顺序，如果按照现有的方案实施，则会存在很多冗余代码 +5. 按照策略模式，不同的校验规则，组装不同的策略，也可以单独抽取出去，独立维护，更清晰 +6. validate 内部按照模版模式，调用 `isValidate` 方法，每个单独的 Validator 不需要额外去调用 next，设计更加健壮，防止别人漏写 @@ -396,5 +401,5 @@ OrderSumitValidatorFactory { - 优先级的关系维护在不同的子类中，各司其职，独立维护 +最后选什么？组合优于继承，个人倾向使用责任链模式去组织代码。关于责任链设计模式的文章也可以看这篇[文章](./../Chapter6%20-%20Design%20Pattern/6.23.md) -最后选什么？组合优于继承，个人倾向使用责任链模式去组织代码。 diff --git a/Chapter1 - iOS/1.48.md b/Chapter1 - iOS/1.48.md index 5c611a1..f019f80 100644 --- a/Chapter1 - iOS/1.48.md +++ b/Chapter1 - iOS/1.48.md @@ -32,8 +32,12 @@ ``` ### 类别的作用 - -拓展当前类，为类添加方法 +可以把类的实现分开在几个不同的源文件里，所以好处是： +- 减少耽搁文件的代码行数 +- 可以把不痛的功能组织到不同的 category 里 +- 可以由多个开发者共同完成一个大的类，方便协作 +- 拓展当前类，为类添加方法 +- 声明私有方法 ### 类别的局限性 diff --git a/Chapter6 - Design Pattern/6.10.md b/Chapter6 - Design Pattern/6.10.md new file mode 100644 index 0000000..49de7fa --- /dev/null +++ b/Chapter6 - Design Pattern/6.10.md @@ -0,0 +1,314 @@ +# 工厂模式 + +> 什么时候该用工厂模式？相对于直接 new 来创建对象，用工厂模式来创建究竟有什么好处呢？ + +## 简单工厂（Simple Factory） +一般情况下，工厂模式分为三种更加细分的类型：简单工厂、工厂方法和抽象工厂。不过，在 GoF 的《设计模式》一书中，它将简单工厂模式看作是工厂方法模式的一种特例，所以工厂模式只被分成了工厂方法和抽象工厂两类。实际上，前面一种分类方法更加常见。 + +我们根据配置文件的后缀（json、xml、yaml、properties），选择不同的解析器（JsonRuleConfigParser、XmlRuleConfigParser......），将存储在文件中的配置解析成内存对象 RuleConfig。 +``` +public class RuleConfigSource { + public RuleConfig load(String ruleConfigFilePath) { + String ruleConfigFileExtension = getFileExtension(ruleConfigFilePath); + IRuleConfigParser parser = null; + if ("json".equalsIgnoreCase(ruleConfigFileExtension)) { + parser = new JsonRuleConfigParser(); + } else if ("xml".equalsIgnoreCase(ruleConfigFileExtension)) { + parser = new XmlRuleConfigParser(); + } else if ("yaml".equalsIgnoreCase(ruleConfigFileExtension)) { + parser = new YamlRuleConfigParser(); + } else if ("properties".equalsIgnoreCase(ruleConfigFileExtension)) { + parser = new PropertiesRuleConfigParser(); + } else { + throw new InvalidRuleConfigException("Rule config file format is not supported: " + ruleConfigFilePath) + } + String configText = ""; + //从ruleConfigFilePath文件中读取配置文本到configText中 + RuleConfig ruleConfig = parser.parse(configText); + return ruleConfig; + } + + private String getFileExtension(String filePath) { + //...解析文件名获取扩展名，比如rule.json，返回json + return "json"; + } +} +``` +在“规范和重构”那一部分中，我们有讲到，为了让代码逻辑更加清晰，可读性更好，我们要善于将功能独立的代码块封装成函数。按照这个设计思路，我们可以将代码中涉及 parser 创建的部分逻辑剥离出来，抽象成 createParser() 函数。重构之后的代码如下所示： + +``` +public RuleConfig load(String ruleConfigFilePath) { + String ruleConfigFileExtension = getFileExtension(ruleConfigFilePath); + IRuleConfigParser parser = createParser(ruleConfigFileExtension); + if (parser == null) { + throw new InvalidRuleConfigException("Rule config file format is not supported: " + ruleConfigFilePath) + } + String configText = ""; + //从ruleConfigFilePath文件中读取配置文本到configText中 + RuleConfig ruleConfig = parser.parse(configText); + return ruleConfig; +} +private String getFileExtension(String filePath) { + //...解析文件名获取扩展名，比如rule.json，返回json + return "json"; +} + +private IRuleConfigParser createParser(String configFormat) { + IRuleConfigParser parser = null; + if ("json".equalsIgnoreCase(configFormat)) { + parser = new JsonRuleConfigParser(); + } else if ("xml".equalsIgnoreCase(configFormat)) { + parser = new XmlRuleConfigParser(); + } else if ("yaml".equalsIgnoreCase(configFormat)) { + parser = new YamlRuleConfigParser(); + } else if ("properties".equalsIgnoreCase(configFormat)) { + parser = new PropertiesRuleConfigParser(); + } + return parser; +} +``` +为了让类的职责更加单一、代码更加清晰，我们还可以进一步将 createParser() 函数剥离到一个独立的类中，让这个类只负责对象的创建。而这个类就是我们现在要讲的简单工厂模式类。具体的代码如下所示： +``` +public class RuleConfigParserFactory { + public static IRuleConfigParser createParser(String configFormat) { + IRuleConfigParser parser = null; + if ("json".equalsIgnoreCase(configFormat)) { + parser = new JsonRuleConfigParser(); + } else if ("xml".equalsIgnoreCase(configFormat)) { + parser = new XmlRuleConfigParser(); + } else if ("yaml".equalsIgnoreCase(configFormat)) { + parser = new YamlRuleConfigParser(); + } else if ("properties".equalsIgnoreCase(configFormat)) { + parser = new PropertiesRuleConfigParser(); + } + return parser; + } +} +``` +大部分工厂类都是以 Factory 结尾的，这样子标准些，见名知意。 + +在上面的代码实现中，我们每次调用 RuleConfigParserFactory 的 createParser() 的时候，都要创建一个新的 parser。实际上，如果 parser 可以复用，为了节省内存和对象创建的时间，我们可以将 parser 事先创建好缓存起来。当调用 createParser() 函数的时候，我们从缓存中取出 parser 对象直接使用 + +这有点类似单例模式和简单工厂模式的结合，具体的代码实现如下所示。在接下来的讲解中，我们把上一种实现方法叫作简单工厂模式的第一种实现方法，把下面这种实现方法叫作简单工厂模式的第二种实现方法 + +``` +public class RuleConfigParserFactory { + private static final Map cachedParsers = new HashMap(); + static { + cachedParsers.put("json", new JsonRuleConfigParser()); + cachedParsers.put("xml", new XmlRuleConfigParser()); + cachedParsers.put("yaml", new YamlRuleConfigParser()); + cachedParsers.put("properties", new PropertiesRuleConfigParser()); + } + public static IRuleConfigParser createParser(String configFormat) { + if (configFormat == null || configFormat.isEmpty()) { + return null;//返回null还是IllegalArgumentException全凭你自己说了算 + } + IRuleConfigParser parser = cachedParsers.get(configFormat.toLowerCase()); + return parser; + } +} +``` + +对于上面两种简单工厂模式的实现方法，如果我们要添加新的 parser，那势必要改动到 RuleConfigParserFactory 的代码，那这是不是违反开闭原则呢？实际上，如果不是需要频繁地添加新的 parser，只是偶尔修改一下 RuleConfigParserFactory 代码，稍微不符合开闭原则，也是完全可以接受的。 + +除此之外，在 RuleConfigParserFactory 的第一种代码实现中，有一组 if 分支判断逻辑，是不是应该用多态或其他设计模式来替代呢？实际上，如果 if 分支并不是很多，代码中有 if 分支也是完全可以接受的。应用多态或设计模式来替代 if 分支判断逻辑，也并不是没有任何缺点的，它虽然提高了代码的扩展性，更加符合开闭原则，但也增加了类的个数，牺牲了代码的可读性。 + +总结一下，尽管简单工厂模式的代码实现中，有多处 if 分支判断逻辑，违背开闭原则，但**权衡扩展性和可读性**，这样的代码实现在大多数情况下（比如，不需要频繁地添加 parser，也没有太多的 parser）是没有问题的。 + +## 工厂方法（Factory Method） +如果我们非得要将 if 分支逻辑去掉，那该怎么办呢？比较经典处理方法就是利用多态。按照多态的实现思路，对上面的代码进行重构。重构之后的代码如下所示 + +``` +public interface IRuleConfigParserFactory { + IRuleConfigParser createParser(); +} +public class JsonRuleConfigParserFactory implements IRuleConfigParserFactory { + @Override + public IRuleConfigParser createParser() { + return new JsonRuleConfigParser(); + } +} +public class XmlRuleConfigParserFactory implements IRuleConfigParserFactory { + @Override + public IRuleConfigParser createParser() { + return new XmlRuleConfigParser(); + } +} +public class YamlRuleConfigParserFactory implements IRuleConfigParserFactory { + @Override + public IRuleConfigParser createParser() { + return new YamlRuleConfigParser(); + } +} +public class PropertiesRuleConfigParserFactory implements IRuleConfigParserFactory + @Override + public IRuleConfigParser createParser() { + return new PropertiesRuleConfigParser(); + } +} +``` +实际上，这就是工厂方法模式的典型代码实现。这样当我们新增一种 parser 的时候，只需要新增一个实现了 IRuleConfigParserFactory 接口的 Factory 类即可。所以，**工厂方法模式比起简单工厂模式更加符合开闭原则** + +从上面的工厂方法的实现来看，一切都很完美，但是实际上存在挺大的问题。问题存在于这些工厂类的使用上。接下来，我们看一下，如何用这些工厂类来实现 RuleConfigSource 的 load() 函数。具体的代码如下所示 +``` +public class RuleConfigSource { + public RuleConfig load(String ruleConfigFilePath) { + String ruleConfigFileExtension = getFileExtension(ruleConfigFilePath); + IRuleConfigParserFactory parserFactory = null; + if ("json".equalsIgnoreCase(ruleConfigFileExtension)) { + parserFactory = new JsonRuleConfigParserFactory(); + } else if ("xml".equalsIgnoreCase(ruleConfigFileExtension)) { + parserFactory = new XmlRuleConfigParserFactory(); + } else if ("yaml".equalsIgnoreCase(ruleConfigFileExtension)) { + parserFactory = new YamlRuleConfigParserFactory(); + } else if ("properties".equalsIgnoreCase(ruleConfigFileExtension)) { + parserFactory = new PropertiesRuleConfigParserFactory(); + } else { + throw new InvalidRuleConfigException("Rule config file format is not supported: " + ruleConfigFilePath) + } + IRuleConfigParser parser = parserFactory.createParser(); + String configText = ""; + //从ruleConfigFilePath文件中读取配置文本到configText中 + RuleConfig ruleConfig = parser.parse(configText); + return ruleConfig; + } + private String getFileExtension(String filePath) { + //...解析文件名获取扩展名，比如rule.json，返回json + return "json"; + } +} +``` +从上面的代码实现来看，工厂类对象的创建逻辑又耦合进了 load() 函数中，跟我们最初的代码版本非常相似，引入工厂方法非但没有解决问题，反倒让设计变得更加复杂了。那怎么来解决这个问题呢？ + +我们可以为工厂类再创建一个简单工厂，也就是工厂的工厂，用来创建工厂类对象 +``` +public class RuleConfigSource { + public RuleConfig load(String ruleConfigFilePath) { + String ruleConfigFileExtension = getFileExtension(ruleConfigFilePath); + IRuleConfigParserFactory parserFactory = RuleConfigParserFactoryMap.getPars + if (parserFactory == null) { + throw new InvalidRuleConfigException("Rule config file format is not supported: " + ruleConfigFilePath) + } + IRuleConfigParser parser = parserFactory.createParser(); + String configText = ""; + //从ruleConfigFilePath文件中读取配置文本到configText中 + RuleConfig ruleConfig = parser.parse(configText); + return ruleConfig; + } + private String getFileExtension(String filePath) { + //...解析文件名获取扩展名，比如rule.json，返回json + return "json"; + } +} +//因为工厂类只包含方法，不包含成员变量，完全可以复用， +//不需要每次都创建新的工厂类对象，所以，简单工厂模式的第二种实现思路更加合适。 +public class RuleConfigParserFactoryMap { //工厂的工厂 + private static final Map cachedFactories = + static { + cachedFactories.put("json", new JsonRuleConfigParserFactory()); + cachedFactories.put("xml", new XmlRuleConfigParserFactory()); + cachedFactories.put("yaml", new YamlRuleConfigParserFactory()); + cachedFactories.put("properties", new PropertiesRuleConfigParserFactory()) + } + public static IRuleConfigParserFactory getParserFactory(String type) { + if (type == null || type.isEmpty()) { + return null; + } + IRuleConfigParserFactory parserFactory = cachedFactories.get(type.toLowerCa + return parserFactory; + } +} +``` +当我们需要添加新的规则配置解析器的时候，我们只需要创建新的 parser 类和 parserfactory 类，并且在 RuleConfigParserFactoryMap 类中，将新的 parser factory 对象添加到 cachedFactories 中即可。代码的改动非常少，基本上符合开闭原则。 + +实际上，对于规则配置文件解析这个应用场景来说，工厂模式需要额外创建诸多 Factory 类，也会增加代码的复杂性，而且，每个 Factory 类只是做简单的 new 操作，功能非常单薄（只有一行代码），也没必要设计成独立的类，所以，在这个应用场景下，简单工厂模式简单好用，比工方法厂模式更加合适。 + +什么时候该用工厂方法模式，而非简单工厂模式呢？ + +之所以将某个代码块剥离出来，独立为函数或者类，原因是这个代码块的逻辑过于复杂，剥离之后能让代码更加清晰，更加可读、可维护。但是，如果代码块本身并不 +复杂，就几行代码而已，我们完全没必要将它拆分成单独的函数或者类。 + +基于这个设计思想，当对象的创建逻辑比较复杂，不只是简单的 new 一下就可以，而是要组合其他类对象，做各种初始化操作的时候，我们推荐使用工厂方法模式，将复杂的创建逻辑拆分到多个工厂类中，让每个工厂类都不至于过于复杂。而使用简单工厂模式，将所有的创建逻辑都放到一个工厂类中，会导致这个工厂类变得很复杂。 + +除此之外，在某些场景下，如果对象不可复用，那工厂类每次都要返回不同的对象。如果我们使用简单工厂模式来实现，就只能选择第一种包含 if 分支逻辑的实现方式。如果我们还想避免烦人的 if-else 分支逻辑，这个时候，我们就推荐使用工厂方法模式。 + +## 抽象工厂（Abstract Factory） +在简单工厂和工厂方法中，类只有一种分类方式。比如，在规则配置解析那个例子中，解析器类只会根据配置文件格式（Json、Xml、Yaml......）来分类。但是，如果类有两种分类方式，比如，我们既可以按照配置文件格式来分类，也可以按照解析的对象（Rule 规则配置还是 System 系统配置）来分类，那就会对应下面这 8 个 parser 类。 + +针对规则配置的解析器：基于接口IRuleConfigParser +- JsonRuleConfigParser +- XmlRuleConfigParser +- YamlRuleConfigParser +- PropertiesRuleConfigParser +针对系统配置的解析器：基于接口ISystemConfigParser +- JsonSystemConfigParser +- XmlSystemConfigParser +- YamlSystemConfigParser +- PropertiesSystemConfigParser + +针对这种特殊的场景，如果还是继续用工厂方法来实现的话，我们要针对每个 parser 都编写一个工厂类，也就是要编写 8 个工厂类。如果我们未来还需要增加针对业务配置的解析器（比如 IBizConfigParser），那就要再对应地增加 4 个工厂类。而我们知道，过多的类 +也会让系统难维护。这个问题该怎么解决呢？ + +抽象工厂就是针对这种非常特殊的场景而诞生的。我们可以让一个工厂负责创建多个不同类型的对象（IRuleConfigParser、ISystemConfigParser 等），而不是只创建一种 parser 对象。这样就可以有效地减少工厂类的个数。具体的代码实现如下所示： +``` +public interface IConfigParserFactory { + IRuleConfigParser createRuleParser(); + ISystemConfigParser createSystemParser(); + //此处可以扩展新的parser类型，比如IBizConfigParser +} + +public class JsonConfigParserFactory implements IConfigParserFactory { + @Override + public IRuleConfigParser createRuleParser() { + return new JsonRuleConfigParser(); + } + @Override + public ISystemConfigParser createSystemParser() { + return new JsonSystemConfigParser(); + } +} + +public class XmlConfigParserFactory implements IConfigParserFactory { + @Override + public IRuleConfigParser createRuleParser() { + return new XmlRuleConfigParser(); + } + @Override + public ISystemConfigParser createSystemParser() { + return new XmlSystemConfigParser(); + } +} +//... +``` + +## 场景 +当创建逻辑比较复杂，是一个“大工程”的时候，我们就考虑使用工厂模式，封装对象的创建过程，将对象的创建和使用相分离。何为创建逻辑比较复杂呢？ +第一种情况：类似规则配置解析的例子，代码中存在 if-else 分支判断，动态地根据不同的类型创建不同的对象。针对这种情况，我们就考虑使用工厂模式，将这一大坨 if-else 创建对象的代码抽离出来，放到工厂类中。 + +还有一种情况，尽管我们不需要根据不同的类型创建不同的对象，但是，单个对象本身的创建过程比较复杂，比如前面提到的要组合其他类对象，做各种初始化操作。在这种情况下，我们也可以考虑使用工厂模式，将对象的创建过程封装到工厂类中。 + +对于第一种情况，当每个对象的创建逻辑都比较简单的时候，我推荐使用简单工厂模式，将多个对象的创建逻辑放到一个工厂类中。当每个对象的创建逻辑都比较复杂的时候，为了避免设计一个过于庞大的简单工厂类，我推荐使用工厂方法模式，将创建逻辑拆分得更细，每个对象的创建逻辑独立到各自的工厂类中。同理，对于第二种情况，因为单个对象本身的创建逻辑就比较复杂，所以，我建议使用工厂方法模式。 + +一个 high-level 的视觉分析，什么场景下需使用工厂模式: +- 封装变化：创建逻辑有可能变化，封装成工厂类之后，创建逻辑的变更对调用者透明。 +- 代码复用：创建代码抽离到独立的工厂类之后可以复用。 +- 隔离复杂性：封装复杂的创建逻辑，调用者无需了解如何创建对象。 +- 控制复杂度：将创建代码抽离出来，让原本的函数或类职责更单一，代码更简洁。 + + +## 如何设计实现一个 Dependency Injection 框架 +赖注入框架，或者叫依赖注入容器（Dependency Injection Container），简称 DI 容器。需要搞清楚这样几个问题： +- DI 容器跟我们讲的工厂模式又有何区别和联系？ +- DI 容器的核心功能有哪些 +- 如何实现一个简单的 DI 容器？ + +### 工厂模式和 DI 容器有何区别？ +**DI 容器底层最基本的设计思路就是基于工厂模式的**。DI 容器相当于一个大的工厂类，负责在程序启动的时候，根据配置（要创建哪些类对象，每个类对象的创建需要依赖哪些其他类对象）事先创建好对象。当应用程序需要使用某个类对象的时候，直接从容器中获取即可。正是因为它持有一堆对象，所以这个框架才被称为“容器”。 + +DI 容器相对于我们上节课讲的工厂模式的例子来说，它处理的是更大的对象创建工程。一个工厂类只负责某个类对象或者某一组相关类对象（继承自同一抽 +象类或者接口的子类）的创建，而 DI 容器负责的是整个应用中所有类对象的创建。除此之外，DI 容器负责的事情要比单纯的工厂模式要多。比如，它还包括配置的解析、对象生命周期的管理。接下来，我们就详细讲讲，一个简单的 DI 容器应该包含哪些核心功能。 + +### DI 容器的核心功能有哪些？ +总结一下，一个简单的 DI 容器的核心功能一般有三个：配置解析、对象创建和对象生命周期管理 + diff --git a/Chapter6 - Design Pattern/6.11.md b/Chapter6 - Design Pattern/6.11.md new file mode 100644 index 0000000..870d8a7 --- /dev/null +++ b/Chapter6 - Design Pattern/6.11.md @@ -0,0 +1,193 @@ +# 建造者模式 +Builder 模式，中文翻译为建造者模式或者构建者模式，也有人叫它生成器模式。弄清楚建造者模式需要搞定下面2个问题： +- 直接使用构造函数或者配合 set 方法就能创建对象，为什么还需要建造者模式来创建呢？ +- 建造者模式和工厂模式都可以创建对象，那它们两个的区 + +## 为什么需要建造者模式？ +创建一个对象最常用的方式是，使用 new 关键字调用类的构造函数来完成。我的问题是，什么情况下这种方式就不适用了，就需要采用建造者模式来创建对象呢？你可以先思考一下，下面我通过一个例子来带你看一下。 + +设计面试题：我们需要定义一个资源池配置类 ResourcePoolConfig。这里的资源池，你可以简单理解为线程池、连接池、对象池等。在这个资源池配置类中，有以下几个成员变量，也就是可配置项。现在，请你编写代码实现这个 ResourcePoolConfig 类。 +- name：资源名称，必填，没有默认值 +- maxTotal：最大总资源数量，不是必填，默认值8 +- maxIdle：最大空闲资源数量，不是必填，默认值8 +- minIdle：最小空闲资源数量，不是必填，默认值0 +设计一下这个类 +``` +public class ResourcePoolConfig { + private static final int DEFAULT_MAX_TOTAL = 8; + private static final int DEFAULT_MAX_IDLE = 8; + private static final int DEFAULT_MIN_IDLE = 0; + private String name; + private int maxTotal = DEFAULT_MAX_TOTAL; + private int maxIdle = DEFAULT_MAX_IDLE; + private int minIdle = DEFAULT_MIN_IDLE; + public ResourcePoolConfig(String name, Integer maxTotal, Integer maxIdle, Integer minIdle) { + if (StringUtils.isBlank(name)) { + throw new IllegalArgumentException("name should not be empty."); + } + this.name = name; + if (maxTotal != null) { + if (maxTotal <= 0) { + throw new IllegalArgumentException("maxTotal should be positive."); + } + this.maxTotal = maxTotal; + } + if (maxIdle != null) { + if (maxIdle < 0) { + throw new IllegalArgumentException("maxIdle should not be negative."); + } + this.maxIdle = maxIdle; + } + if (minIdle != null) { + if (minIdle < 0) { + throw new IllegalArgumentException("minIdle should not be negative."); + } + this.minIdle = minIdle; + } + } + //...省略getter方法... +} +``` +现在，ResourcePoolConfig 只有 4 个可配置项，对应到构造函数中，也只有 4 个参数，参数的个数不多。但是，如果可配置项逐渐增多，变成了 8 个、10 个，甚至更多，那继续沿用现在的设计思路，构造函数的参数列表会变得很长，代码在可读性和易用性上都会变差。在使用构造函数的时候，我们就容易搞错各参数的顺序，传递进错误的参数值，导致非常隐蔽的 bug。 + +``` +// 参数太多，导致可读性差、参数可能传递错误 +ResourcePoolConfig config = new ResourcePoolConfig("dbconnectionpool", 16, ...); +``` + +方法二：解决这个问题的办法你应该也已经想到了，那就是用 set() 函数来给成员变量赋值，以替代冗长的构造函数。我们直接看代码，具体如下所示。其中，配置项 name 是必填的，所以我们把它放到构造函数中设置，强制创建类对象的时候就要填写。其他配置项 maxTotal、maxIdle、minIdle 都不是必填的，所以我们通过 set() 函数来设置，让使用者自主选择填写或者不填写。 + +``` +public class ResourcePoolConfig { + private static final int DEFAULT_MAX_TOTAL = 8; + private static final int DEFAULT_MAX_IDLE = 8; + private static final int DEFAULT_MIN_IDLE = 0; + private String name; + private int maxTotal = DEFAULT_MAX_TOTAL; + private int maxIdle = DEFAULT_MAX_IDLE; + private int minIdle = DEFAULT_MIN_IDLE; + public ResourcePoolConfig(String name) { + if (StringUtils.isBlank(name)) { + throw new IllegalArgumentException("name should not be empty."); + } + this.name = name; + } + public void setMaxTotal(int maxTotal) { + if (maxTotal <= 0) { + throw new IllegalArgumentException("maxTotal should be positive."); + } + this.maxTotal = maxTotal; + } + + //... +} +``` +接下来，我们来看新的 ResourcePoolConfig 类该如何使用。我写了一个示例代码，如下所示。没有了冗长的函数调用和参数列表，代码在可读性和易用性上提高了很多。 +``` +// ResourcePoolConfig使用举例 +ResourcePoolConfig config = new ResourcePoolConfig("dbconnectionpool"); +config.setMaxTotal(16); +config.setMaxIdle(8); +``` + +问题改变了，假设配置项之间有一定的依赖关系，比如，如果用户设置了 maxTotal、maxIdle、minIdle 其中一个，就必须显式地设置另外两个；或者配置项之间有一定的约束条件，比如，maxIdle 和 minIdle 要小于等于 maxTotal。如果我们继续使用现在的设计思路，那这些配置项之间的依赖关系或者约束条件的校验逻辑就无处安放了。 + +如果我们希望 ResourcePoolConfig 类对象是不可变对象，也就是说，对象在创建好之后，就不能再修改内部的属性值。要实现这个功能，我们就不能在ResourcePoolConfig 类中暴露 set() 方法。 + +这个时候建造者模式就应运而生了。 + +我们**可以把校验逻辑放置到 Builder 类中，先创建建造者，并且通过 set() 方法设置建造者的变量值，然后在使用 build() 方法真正创建对象之前，做集中的校验，校验通过之后才会创建对象**。除此之外，我们把 ResourcePoolConfig 的构造函数改为 private 私有权限。这样我们就只能通过建造者来创建ResourcePoolConfig 类对象。并且，ResourcePoolConfig 没有提供任何 set() 方法，这样我们创建出来的对象就是不可变对象了。 + +``` +public class ResourcePoolConfig { + private String name; + private int maxTotal; + private int maxIdle; + private int minIdle; + private ResourcePoolConfig(Builder builder) { + this.name = builder.name; + this.maxTotal = builder.maxTotal; + this.maxIdle = builder.maxIdle; + this.minIdle = builder.minIdle; + } + //...省略getter方法... + //我们将Builder类设计成了ResourcePoolConfig的内部类。 + //我们也可以将Builder类设计成独立的非内部类ResourcePoolConfigBuilder。 + public static class Builder { + private static final int DEFAULT_MAX_TOTAL = 8; + private static final int DEFAULT_MAX_IDLE = 8; + private static final int DEFAULT_MIN_IDLE = 0; + private String name; + private int maxTotal = DEFAULT_MAX_TOTAL; + private int maxIdle = DEFAULT_MAX_IDLE; + private int minIdle = DEFAULT_MIN_IDLE; + public ResourcePoolConfig build() { + // 校验逻辑放到这里来做，包括必填项校验、依赖关系校验、约束条件校验等 + if (StringUtils.isBlank(name)) { + throw new IllegalArgumentException("..."); + } + if (maxIdle > maxTotal) { + throw new IllegalArgumentException("..."); + } + if (minIdle > maxTotal || minIdle > maxIdle) { + throw new IllegalArgumentException("..."); + } + return new ResourcePoolConfig(this); + } + public Builder setName(String name) { + if (StringUtils.isBlank(name)) { + throw new IllegalArgumentException("..."); + } + this.name = name; + return this; + } + public Builder setMaxTotal(int maxTotal) { + if (maxTotal <= 0) { + throw new IllegalArgumentException("..."); + } + this.maxTotal = maxTotal; + return this; + } + public Builder setMaxIdle(int maxIdle) { + if (maxIdle < 0) { + throw new IllegalArgumentException("..."); + } + this.maxIdle = maxIdle; + return this; + } + public Builder setMinIdle(int minIdle) { + if (minIdle < 0) { + throw new IllegalArgumentException("..."); + } + this.minIdle = minIdle; + return this; + } + } +} + +// 这段代码会抛出IllegalArgumentException，因为minIdle>maxIdle +ResourcePoolConfig config = new ResourcePoolConfig.Builder() +.setName("dbconnectionpool") +.setMaxTotal(16) +.setMaxIdle(10) +.setMinIdle(12) +.build(); +``` + +**使用建造者模式创建对象，还能避免对象存在无效状态**。比如我们定义了一个长方形类，如果不使用建造者模式，采用先创建后 set 的方式，那就会 +导致在第一个 set 之后，对象处于无效状态。具体代码如下所示 +``` +Rectangle r = new Rectange(); // r is invalid +r.setWidth(2); // r is invalid +r.setHeight(3); // r is valid +``` +为了避免这种无效状态的存在，我们就需要使用构造函数一次性初始化好所有的成员变量。如果构造函数参数过多，我们就需要考虑使用建造者模式，先设置建造者的变量，然后再一次性地创建对象，让对象一直处于有效状态。 + +``` +Rectangle r = new Rectange.Builder().setWidth(2).setHeight(3).build(); +``` + +## 建造者模式和工厂模式有何异同 +建造者模式是让建造者类来负责对象的创建工作。工厂模式，是由工厂类来负责对象创建的工作。那它们之间有什么区别呢？ + +实际上，工厂模式是用来创建不同但是相关类型的对象（继承同一父类或者接口的一组子类），由给定的参数来决定创建哪种类型的对象。建造者模式是用来创建一种类型的复杂对象，通过设置不同的可选参数，“定制化”地创建不同的对象。 \ No newline at end of file diff --git a/Chapter6 - Design Pattern/6.12.md b/Chapter6 - Design Pattern/6.12.md new file mode 100644 index 0000000..ea899ac --- /dev/null +++ b/Chapter6 - Design Pattern/6.12.md @@ -0,0 +1,37 @@ +# 原型模式 +对于创建型模式，之前的文章已经讲了单例模式、工厂模式、建造者模式，今天我们来讲最后一个：原型模式。 + +对于熟悉 JavaScript 语言的前端程序员来说，原型模式是一种比较常用的开发模式。这是因为，有别于 Java、C++ 等基于类的面向对象编程语言，JavaScript 是一种基于原型的面向对象编程语言。即便 JavaScript 现在也引入了类的概念，但它也只是基于原型的语法糖而已。不过，如果你熟悉的是 Java、C++ 等这些编程语言，那在实际的开发中，就很少用到原型模式了 + +## 原型模式的原理与应用 +如果对象的创建成本比较大，而同一个类的不同对象之间差别不大（大部分字段都相同），在这种情况下，我们可以利用对已有对象（原型）进行复制（或者叫拷贝）的方式来创建新对象，以达到节省创建时间的目的。这种基于原型来创建对象的方式就叫作原型设计模式 （Prototype Design Pattern），简称原型模式。 + +## 何为“对象的创建成本比较大”？ +创建对象包含的申请内存、给成员变量赋值这一过程，本身并不会花费太多时间，或者说对于大部分业务系统来说，这点时间完全是可以忽略的。应用一个复杂的模式，只得到一点点的性能提升，这就是所谓的过度设计，得不偿失。 + +但是，如果对象中的数据需要经过复杂的计算才能得到（比如排序、计算哈希值），或者需要从 RPC、网络、数据库、文件系统等非常慢速的 IO 中读取，这种情况下，我们就可以利用原型模式，从其他已有对象中直接拷贝得到，而不用每次在创建新对象的时候，都重复执行这些耗时的操作。 + +举个例子： +假设数据库中存储了大约 10 万条“搜索关键词”信息，每条信息包含关键词、关键词被搜索的次数、信息最近被更新的时间等。系统 A 在启动的时候会加载这份数据到内存中，用于处理某些其他的业务需求。为了方便快速地查找某个关键词对应的信息，我们给关键词建立一个散列表索引。 + +不过，我们还有另外一个系统 B，专门用来分析搜索日志，定期（比如间隔 10 分钟）批量地更新数据库中的数据，并且标记为新的数据版本。比如，在下面的示例图中，我们对 v2 版本的数据进行更新，得到 v3 版本的数据。这里我们假设只有更新和新添关键词，没有删除关键词的行为 + +为了保证系统 A 中数据的实时性（不一定非常实时，但数据也不能太旧），系统 A 需要定期根据数据库中的数据，更新内存中的索引和数据。 + +要求，任何时刻，系统 A 的所有数据都是一个版本的，要么都是版本 a，要么都是版本 b，不能有的是版本 a，有的是版本 b。那刚刚的更新方式就不能满足这个要求了。除此之外，我们还要求：在更新内存数据的时候，系统 A不能处于不可用状态，也就是不能停机更新数据 + +方案：我们把正在使用的数据的版本定义为“服务版本”，当我们要更新内存中的数据的时候，我们并不是直接在服务版本（假设是版本 a 数据）上更新，而是重新创建另一个版本数据（假设是版本 b 数据），等新的版本数据建好之后，再一次性地将服务版本从版本 a 切换到版本 b。这样既保证了数据一直可用，又避免了中间状态的存在。 + +可以利用语言提供的 Java 的 clone 或者 OC 的 copy 来实现复制一个对象。但存在深拷贝和浅拷贝2个概念。 + +## 原型模式的实现方式：深拷贝和浅拷贝 +浅拷贝只会复制对象中基本数据类型数据和引用对象的内存地址，不会递归地复制引用对象，以及引用对象的引用对象......而深拷贝得到的是一份完完全全独立的对象。所以，深拷贝比起浅拷贝来说，更加耗时，更加耗内存空间。 + +那如何实现深拷贝呢？总结一下的话，有下面两种方法。 + +第一种方法：递归拷贝对象、对象的引用对象以及引用对象的引用对象......直到要拷贝的对象只包含基本数据类型数据，没有引用对象为止 +第二种方法：先将对象序列化，然后再反序列化成新的对象。 + + + +风险：如果要拷贝的对象是不可变对象，浅拷贝共享不可变对象是没问题的，但对于可变对象来说，浅拷贝得到的对象和原始对象会共享部分数据，就有可能出现数据被修改的风险，也就变得复杂多了 diff --git a/Chapter6 - Design Pattern/6.13.md b/Chapter6 - Design Pattern/6.13.md new file mode 100644 index 0000000..dd4adc3 --- /dev/null +++ b/Chapter6 - Design Pattern/6.13.md @@ -0,0 +1,178 @@ +# 代理模式 +接下来要开始学习另外一种类型的设计模式：结构型模式。结构型模式主要总结了一些类或对象组合在一起的经典结构，这些经典的结构可以解决特定应用场景的问题。结构型模式包括：代理模式、桥接模式、装饰器模式、适配器模式、门面模式、组合模式、享元模式。今天我们要讲其中的代理模式。它也是在实际开发中经常被用到的一种设计模式。 + +## 原理解析 +代理模式（Proxy Design Pattern）的原理和代码实现都不难掌握。它在不改变原始类（或叫被代理类）代码的情况下，通过引入代理类来给原始类附加功能 + +开发了一个 MetricsCollector 类，用来收集接口请求的原始数据，比如访问时间、处理时长等。在业务系统中，我们采用如下方式来使用这个 MetricsCollector 类： + +``` +public class UserController { + //...省略其他属性和方法... + private MetricsCollector metricsCollector; // 依赖注入 + public UserVo login(String telephone, String password) { + long startTimestamp = System.currentTimeMillis(); + // ... 省略login逻辑... + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + RequestInfo requestInfo = new RequestInfo("login", responseTime, startTimes + metricsCollector.recordRequest(requestInfo); + //...返回UserVo数据... + } + public UserVo register(String telephone, String password) { + long startTimestamp = System.currentTimeMillis(); + // ... 省略register逻辑... + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + RequestInfo requestInfo = new RequestInfo("register", responseTime, startTi + metricsCollector.recordRequest(requestInfo); + //...返回UserVo数据... + } +} +``` +上面代码存在2个问题： +1. 性能计数器框架代码侵入到业务代码中，跟业务代码高度耦合。如果未来需要替换这个框架，那替换的成本会比较大 +2. 收集接口请求的代码跟业务代码无关，本就不应该放到一个类中。业务类最好职责更加单一，只聚焦业务处理。 + +改进：为了将框架代码和业务代码解耦，代理模式就派上用场了。代理类 UserControllerProxy 和原始类 UserController 实现相同的接口IUserController。UserController 类只负责业务功能。代理类 UserControllerProxy 负责在业务代码执行前后附加其他逻辑代码，并通过委托的方式调用原始类来执行业务代码 + +``` +public interface IUserController { + UserVo login(String telephone, String password); + UserVo register(String telephone, String password); +} +public class UserController implements IUserController { + //...省略其他属性和方法... + @Override + public UserVo login(String telephone, String password) { + //...省略login逻辑... + //...返回UserVo数据... + } + @Override + public UserVo register(String telephone, String password) { + //...省略register逻辑... + //...返回UserVo数据... + } +} +public class UserControllerProxy implements IUserController { + private MetricsCollector metricsCollector; + private UserController userController; + public UserControllerProxy(UserController userController) { + this.userController = userController; + this.metricsCollector = new MetricsCollector(); + } + + @Override + public UserVo login(String telephone, String password) { + long startTimestamp = System.currentTimeMillis(); + // 委托 + UserVo userVo = userController.login(telephone, password); + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + RequestInfo requestInfo = new RequestInfo("login", responseTime, startTimestamp); + metricsCollector.recordRequest(requestInfo); + return userVo; + } + @Override + public UserVo register(String telephone, String password) { + long startTimestamp = System.currentTimeMillis(); + UserVo userVo = userController.register(telephone, password); + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + RequestInfo requestInfo = new RequestInfo("register", responseTime, startTimestamp); + metricsCollector.recordRequest(requestInfo); + return userVo; + } +} +//UserControllerProxy使用举例 +//因为原始类和代理类实现相同的接口，是基于接口而非实现编程 +//将UserController类对象替换为UserControllerProxy类对象，不需要改动太多代码 +IUserController userController = new UserControllerProxy(new UserController()) +``` + +参照基于接口而非实现编程的设计思想，将原始类对象替换为代理类对象的时候，为了让代码改动尽量少，在刚刚的代理模式的代码实现中，代理类和原始类需要实现相同的接口。但是，如果原始类并没有定义接口，并且原始类代码并不是我们开发维护的（比如它来自一个第三方的类库），我们也没办法直接修改原始类，给它重新定义一个接口。在这种情况下，我们该如何实现代理模式呢？ + +对于这种外部类的扩展，我们一般都是采用继承的方式。这里也不例外。我们让代理类继承原始类，然后扩展附加功能。原理很简单，不需要过多解释，你直接看代码就能明白。具体代码如下所示： + +``` +public class UserControllerProxy extends UserController { + private MetricsCollector metricsCollector; + public UserControllerProxy() { + this.metricsCollector = new MetricsCollector(); + } + public UserVo login(String telephone, String password) { + long startTimestamp = System.currentTimeMillis(); + UserVo userVo = super.login(telephone, password); + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + RequestInfo requestInfo = new RequestInfo("login", responseTime, startTimestamp); + metricsCollector.recordRequest(requestInfo); + return userVo; + } + public UserVo register(String telephone, String password) { + long startTimestamp = System.currentTimeMillis(); + UserVo userVo = super.register(telephone, password); + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + RequestInfo requestInfo = new RequestInfo("register", responseTime, startTimestamp); + metricsCollector.recordRequest(requestInfo); + return userVo; + } +} +//UserControllerProxy使用举例 +UserController userController = new UserControllerProxy(); +``` + +## 动态代理 +不过，刚刚的代码实现还是有点问题。一方面，我们需要在代理类中，将原始类中的所有的方法，都重新实现一遍，并且为每个方法都附加相似的代码逻辑。另一方面，如果要添加的附加功能的类有不止一个，我们需要针对每个类都创建一个代理类。 + +我们可以使用动态代理来解决这个问题。所谓动态代理（Dynamic Proxy），就是我们不事先为每个原始类编写代理类，而是在运行的时候，动态地创建原始类对应的代理类，然后在系统中用代理类替换掉原始类 + +具有动态特性的语言可以实现这个功能，比如 OC、Java 的反射。 + +``` +public class MetricsCollectorProxy { + private MetricsCollector metricsCollector; + public MetricsCollectorProxy() { + this.metricsCollector = new MetricsCollector(); + } + public Object createProxy(Object proxiedObject) { + Class[] interfaces = proxiedObject.getClass().getInterfaces(); + DynamicProxyHandler handler = new DynamicProxyHandler(proxiedObject); + return Proxy.newProxyInstance(proxiedObject.getClass().getClassLoader(), in + } + private class DynamicProxyHandler implements InvocationHandler { + private Object proxiedObject; + public DynamicProxyHandler(Object proxiedObject) { + this.proxiedObject = proxiedObject; + } + @Override + public Object invoke(Object proxy, Method method, Object[] args) { + long startTimestamp = System.currentTimeMillis(); + Object result = method.invoke(proxiedObject, args); + long endTimeStamp = System.currentTimeMillis(); + long responseTime = endTimeStamp - startTimestamp; + String apiName = proxiedObject.getClass().getName() + ":" + method.getName; + RequestInfo requestInfo = new RequestInfo(apiName, responseTime, startTimestamp); + metricsCollector.recordRequest(requestInfo); + return result; + } + } +} +//MetricsCollectorProxy使用举例 +MetricsCollectorProxy proxy = new MetricsCollectorProxy(); +IUserController userController = (IUserController) proxy.createProxy(new UserController) +``` +实际上，Spring AOP 底层的实现原理就是基于动态代理。用户配置好需要给哪些类创建代理，并定义好在执行原始类的业务代码前后执行哪些附加功能。Spring 为这些类创建动态代理对象，并在 JVM 中替代原始类对象。原本在代码中执行的原始类的方法，被换作执行代理类的方法，也就实现了给原始类添加附加功能的目的。 + + +## 总结 +### 代理模式的原理与实现 +在不改变原始类（或叫被代理类）的情况下，通过引入代理类来给原始类附加功能。一般情况下，我们让代理类和原始类实现同样的接口。但是，如果原始类并没有定义接口，并且原始类代码并不是我们开发维护的。在这种情况下，我们可以通过让代理类继承原始类的方法来实现代理模式 + +### 动态代理的原理与实现 +静态代理需要针对每个类都创建一个代理类，并且每个代理类中的代码都有点像模板式的“重复”代码，增加了维护成本和开发成本。对于静态代理存在的问题，我们可以通过动态代理来解决。我们不事先为每个原始类编写代理类，而是在运行的时候动态地创建原始类对应的代理类，然后在系统中用代理类替换掉原始类。 + +### 代理模式的应用场景 +代理模式常用在业务系统中开发一些非功能性需求，比如：监控、统计、鉴权、限流、事务、幂等、日志。我们将这些附加功能与业务功能解耦，放到代理类统一处理，让程序员只需要关注业务方面的开发。除此之外，代理模式还可以用在 RPC、缓存等应用场景中 + diff --git a/Chapter6 - Design Pattern/6.14.md b/Chapter6 - Design Pattern/6.14.md new file mode 100644 index 0000000..3cdf4dc --- /dev/null +++ b/Chapter6 - Design Pattern/6.14.md @@ -0,0 +1,89 @@ +# 桥接模式 + +## 概念理解 + +桥接模式也叫作桥梁模式，英文是 Bridge Design Pattern。这个模式可以说是 23 种设计模式中最难理解的模式之一了。我查阅了比较多的书籍和资料之后发现，对于这个模式有两种不同的理解方式。 + +这其中“最纯正”的理解方式，当属 GoF 的《设计模式》一书中对桥接模式的定义。毕竟，这 23 种经典的设计模式，最初就是由这本书总结出来的。在 GoF 的《设计模式》一书中，桥接模式是这么定义的：“Decouple an abstraction from its implementation so that the two can vary independently。”翻译成中文就是：“**将抽象和实现解耦，让它们可以独立变化**” + +很多书籍、资料中，还有另外一种理解方式：“一个类存在两个（或多个）独立变化的维度，我们通过组合的方式，让这两个（或多个）维度可以独立进行扩展。”通 +过组合关系来替代继承关系，避免继承层次的指数级爆炸。这种理解方式非常类似于，我们之前讲过的“组合优于继承”设计原则 + +GoF 给出的定义非常的简短，单凭这一句话，估计没几个人能看懂是什么意思。所以，我们通过 JDBC 驱动的例子来解释一下。JDBC 驱动是桥接模式的经典应用。我们先来看一下，如何利用 JDBC 驱动来查询数据库。具体的代码如下所示 +``` +Class.forName("com.mysql.jdbc.Driver");//加载及注册JDBC驱动程序 +String url = "jdbc:mysql://localhost:3306/sample_db?user=root&password=your_password +Connection con = DriverManager.getConnection(url); +Statement stmt = con.createStatement()； +String query = "select * from test"; +ResultSet rs=stmt.executeQuery(query); +while(rs.next()) { + rs.getString(1); + rs.getInt(2); +} +``` +如果我们想要把 MySQL 数据库换成 Oracle 数据库，只需要把第一行代码中的 com.mysql.jdbc.Driver 换成 oracle.jdbc.driver.OracleDriver 就可以了。当然，也有更灵活的实现方式，我们可以把需要加载的 Driver 类写到配置文件中，当程序启动的时候，自动从配置文件中加载，这样在切换数据库的时候，我们都不需要修改代码，只需要修改配置文件就可以了。 + +分析源码 com.mysql.jdbc.Driver + +``` +package com.mysql.jdbc; +import java.sql.SQLException; +public class Driver extends NonRegisteringDriver implements java.sql.Driver { + static { + try { + java.sql.DriverManager.registerDriver(new Driver()); + } catch (SQLException E) { + throw new RuntimeException("Can't register driver!"); + } + } + /** + * Construct a new driver and register it with DriverManager + * @throws SQLException if a database error occurs. + */ + public Driver() throws SQLException { + // Required for Class.forName().newInstance() + } +} +``` +结合 com.mysql.jdbc.Driver 的代码实现，我们可以发现，当执行 Class.forName(“com.mysql.jdbc.Driver”) 这条语句的时候，实际上是做了两件事情。第一件事情是要求 JVM 查找并加载指定的 Driver 类，第二件事情是执行该类的静态代码，也就是将 MySQL Driver 注册到 DriverManager 类中。 +现在，我们再来看一下，DriverManager 类是干什么用的。具体的代码如下所示。当我们把具体的 Driver 实现类（比如，com.mysql.jdbc.Driver）注册到 DriverManager 之后，后续所有对 JDBC 接口的调用，都会委派到对具体的 Driver 实现类来执行。而 Driver 实现类都实现了相同的接口（java.sql.Driver ），这也是可以灵活切换 Driver 的原因 + +``` +public class DriverManager { + private final static CopyOnWriteArrayList registeredDrivers = new + //... + static { + loadInitialDrivers(); + println("JDBC DriverManager initialized"); + } + //... + public static synchronized void registerDriver(java.sql.Driver driver) throws + if (driver != null) { + registeredDrivers.addIfAbsent(new DriverInfo(driver)); + } else { + throw new NullPointerException(); + } + } + public static Connection getConnection(String url, String user, String password) { + java.util.Properties info = new java.util.Properties(); + if (user != null) { + info.put("user", user); + } + if (password != null) { + info.put("password", password); + } + return (getConnection(url, info, Reflection.getCallerClass())); + } + //... +} +``` + +桥接模式的定义是“将抽象和实现解耦，让它们可以独立变化”。那弄懂定义中“抽象”和“实现”两个概念，就是理解桥接模式的关键。那在 JDBC 这个例子中，什么 +是“抽象”？什么是“实现”呢？ + +实际上，JDBC 本身就相当于“抽象”。注意，这里所说的“抽象”，指的并非“抽象类”或“接口”，而是跟具体的数据库无关的、被抽象出来的一套“类库”。具体的Driver（比如，com.mysql.jdbc.Driver）就相当于“实现”。注意，这里所说的“实现”，也并非指“接口的实现类”，而是跟具体数据库相关的一套“类库”。JDBC 和 Driver 独立开发，通过对象之间的组合关系，组装在一起。JDBC 的所有逻辑操作，最终都委托给 Driver 来执行。 + + +## 总结 +桥接模式有两种理解方式。第一种理解方式是“将抽象和实现解耦，让它们能独立开发”。这种理解方式比较特别，应用场景也不多。另一种理解方式更加简单，类似“组合优于继承”设计原则，这种理解方式更加通用，应用场景比较多。 \ No newline at end of file diff --git a/Chapter6 - Design Pattern/6.15.md b/Chapter6 - Design Pattern/6.15.md new file mode 100644 index 0000000..6a36121 --- /dev/null +++ b/Chapter6 - Design Pattern/6.15.md @@ -0,0 +1,42 @@ +# 装饰器模式 + +装饰器模式，它的代码结构跟桥接模式非常相似，不过，要解决的问题却大不相同。 + +## Java IO 类的“奇怪”用法 +Java IO 类库非常庞大和复杂，有几十个类，负责 IO 数据的读取和写入。如果对 Java IO 类做一下分类，我们可以从下面两个维度将它划分为四类。具体如下所示 + +| |字节流|字符流| +|-|-|-| +|输入流| InputStream| Reader| +|输出流| OutputStream| Writer| + + +针对不同的读取和写入场景，Java IO 又在这四个父类基础之上，扩展出了很多子类。比如字节流的 InputStream 有 ByteArrayInputStream、PipedInputStream... +比如下面的代码 +``` +InputStream in = new FileInputStream("/user/wangzheng/test.txt"); +InputStream bin = new BufferedInputStream(in); +byte[] data = new byte[128]; +while (bin.read(data) != -1) { + //... +} +``` +是不是觉得 JavaIO 很麻烦，创建 FileInputStream 对象，然后再传递给 BufferedInputStream 对象来使用。我在想，Java IO 为什么不设计一个继承 FileInputStream 并且支持缓存的 BufferedFileInputStream 类呢？这样我们就可以像下面的代码中这样，直接创建一个 BufferedFileInputStream 类对象，打开文件读取数据，用起来岂不是更加简单？ + +## 基于继承的设计方案 +如果 InputStream 只有一个子类 FileInputStream 的话，那我们在 FileInputStream 基础之上，再设计一个孙子类 BufferedFileInputStream，也算是可以接受的，毕竟继承结构还算简单。但实际上，继承 InputStream 的子类有很多。我们需要给每一个 InputStream 的子类，再继续派生支持缓存读取的子类 + +在这种情况下，如果我们继续按照继承的方式来实现的话，就需要再继续派生出 DataFileInputStream、DataPipedInputStream 等类。如果我们还需要既支持缓存、又支持按照基本类型读取数据的类，那就要再继续派生出 BufferedDataFileInputStream、BufferedDataPipedInputStream 等 n 多类。这还只是附加了两个增强功能，如果我们需要附加更多的功能，则会导致组合爆炸，类的继承结构变得很复杂，代码不好维护。 + + + +装饰器模式相对于简单的组合关系，还有两个比较特殊的地方： +1. 第一个比较特殊的地方是：装饰器类和原始类继承同样的父类，这样我们可以对原始类“嵌套”多个装饰器类。 +2. 第二个比较特殊的地方是：装饰器类是对功能的增强，这也是装饰器模式应用场景的一个重要特点。 +符合“组合关系”这种代码结构的设计模式有很多，比如之前讲过的代理模式、桥接模式，还有现在的装饰器模式。尽管它们的代码结构很相似，但是每种设计模式的意图是不同的。就拿比较相似的代理模式和装饰器模式来说吧，代理模式中，代理类附加的是跟原始类无关的功能，而在装饰器模式中，装饰器类附加的是跟原始类相关的增强功能。 + +## 价值 +装饰器模式主要解决继承关系过于复杂的问题，通过组合来替代继承。它主要的作用是给原始类添加增强功能。这也是判断是否该用装饰器模式的一个重要的依据。除此之外，装饰器模式还有一个特点，那就是可以对原始类嵌套使用多个装饰器。为了满足这个应用场景，在设计的时候，装饰器类需要跟原始类继承相同的抽象类或者接口。 + +到底是该用代理模式还是装饰器模式呢？ +对于添加缓存这个应用场景使用哪种模式，要看设计者的意图，如果设计者不需要用户关注是否使用缓存功能，要隐藏实现细节，也就是说用户只能看到和使用代理类，那么就使用 proxy 模式；反之，如果设计者需要用户自己决定是否使用缓存的功能，需要用户自己新建原始对象并动态添加缓存功能，那么就使用 decorator 模式。 diff --git a/Chapter6 - Design Pattern/6.16.md b/Chapter6 - Design Pattern/6.16.md new file mode 100644 index 0000000..fa51545 --- /dev/null +++ b/Chapter6 - Design Pattern/6.16.md @@ -0,0 +1,239 @@ +# 适配器模式 + +## 适配器模式的原理 + +适配器模式的英文翻译是 Adapter Design Pattern。顾名思义，这个模式就是用来做适配的，它将不兼容的接口转换为可兼容的接口，让原本由于接口不兼容而不能一起工作的类可以一起工作。举个现实的例子：USB 转接头充当适配器，把两种不兼容的接口，通过转接变得可以一起工作 + +## 适配器模式的实现 +适配器模式有两种实现方式： +- 类适配器，使用继承关系来实现 +- 对象适配器，对象适配器使用组合关系来实现 +举个例子： +- ITarget 表示要转化成的接口定义 +- Adaptee 是一组不兼容 ITarget 接口定义的接口 +- Adaptor 将 Adaptee 转化成一组符合 ITarget 接口定义的接口 + +类适配器: 基于继承 +``` +public interface ITarget { + void f1(); + void f2(); + void fc(); +} +public class Adaptee { + public void fa() { //... } + public void fb() { //... } + public void fc() { //... } +} +public class Adaptor extends Adaptee implements ITarget { + public void f1() { + super.fa(); + } + public void f2() { + //...重新实现f2()... + } + // 这里fc()不需要实现，直接继承自Adaptee，这是跟对象适配器最大的不同点 +} +``` +对象适配器：基于组合 +``` +public interface ITarget { + void f1(); + void f2(); + void fc(); +} +public class Adaptee { + public void fa() { //... } + public void fb() { //... } + public void fc() { //... } +} +public class Adaptor implements ITarget { + private Adaptee adaptee; + public Adaptor(Adaptee adaptee) { + this.adaptee = adaptee; + } + public void f1() { + adaptee.fa(); //委托给Adaptee + } + public void f2() { + //...重新实现f2()... + } + public void fc() { + adaptee.fc(); + } +} +``` +针对这两种实现方式，在实际的开发中，到底该如何选择使用哪一种呢？判断的标准主要有两个，一个是 Adaptee 接口的个数，另一个是 Adaptee 和 ITarget 的契合程度： +- 如果 Adaptee 接口并不多，那两种实现方式都可以。 +- 如果 Adaptee 接口很多，而且 Adaptee 和 ITarget 接口定义大部分都相同，推荐使用类适配器，因为 Adaptor 复用父类 Adaptee 的接口，比起对象适配器的实现方式，Adaptor 的代码量要少一些。 +- 如果 Adaptee 接口很多，而且 Adaptee 和 ITarget 接口定义大部分都不相同，推荐使用对象适配器，因为组合结构相对于继承更加灵活 + +## 适配器模式应用场景总结 +适配器模式可以看作一种“补偿模式”，用来补救设计上的缺陷。应用这种模式算是“无奈之举”。如果在设计初期，我们就能协调规避接口不兼容的问题，那这种模式就没有应用的机会了 + +适配器模式的应用场景是“接口不兼容”。那在实际的开发中，什么情况下才会出现接口不兼容呢？ + +### 封装有缺陷的接口设计 +假设我们依赖的外部系统在接口设计方面有缺陷（比如包含大量静态方法），引入之后会影响到我们自身代码的可测试性。为了隔离设计上的缺陷，我们希望对外部系统提供的接口进行二次封装，抽象出更好的接口设计，这个时候就可以使用适配器模式了。 +``` +public class CD { //这个类来自外部sdk，我们无权修改它的代码 + //... + public static void staticFunction1() { //... } + public void uglyNamingFunction2() { //... } + public void tooManyParamsFunction3(int paramA, int paramB, ...) { //... } + public void lowPerformanceFunction4() { //... } +} +// 使用适配器模式进行重构 +public class ITarget { + void function1(); + void function2(); + void fucntion3(ParamsWrapperDefinition paramsWrapper); + void function4(); + //... +} +// 注意：适配器类的命名不一定非得末尾带Adaptor +public class CDAdaptor extends CD implements ITarget { + //... + public void function1() { + super.staticFunction1(); + } + public void function2() { + super.uglyNamingFucntion2(); + } + public void function3(ParamsWrapperDefinition paramsWrapper) { + super.tooManyParamsFunction3(paramsWrapper.getParamA(), ...); + } + public void function4() { + //...reimplement it... + } +} +``` +### 统一多个类的接口设计 +某个功能的实现依赖多个外部系统（或者说类）。通过适配器模式，将它们的接口适配为统一的接口定义，然后我们就可以使用多态的特性来复用代码逻辑。 + +假设我们的系统要对用户输入的文本内容做敏感词过滤，为了提高过滤的召回率，我们引入了多款第三方敏感词过滤系统，依次对用户输入的内容进行过滤，过滤掉尽可能多的敏感词。但是，每个系统提供的过滤接口都是不同的。这就意味着我们没法复用一套逻辑来调用各个系统。这个时候，我们就可以使用适配器模式，将所有系统的接口适配为统一的接口定义，这样我们可以复用调用敏感词过滤的代码。 + +``` +public class ASensitiveWordsFilter { // A敏感词过滤系统提供的接口 + //text是原始文本，函数输出用***替换敏感词之后的文本 + public String filterSexyWords(String text) { + // ... + } + public String filterPoliticalWords(String text) { + // ... + } +} +public class BSensitiveWordsFilter { // B敏感词过滤系统提供的接口 + public String filter(String text) { + //... + } +} +public class CSensitiveWordsFilter { // C敏感词过滤系统提供的接口 + public String filter(String text, String mask) { + //... + } +} +// 未使用适配器模式之前的代码：代码的可测试性、扩展性不好 +public class RiskManagement { + private ASensitiveWordsFilter aFilter = new ASensitiveWordsFilter(); + private BSensitiveWordsFilter bFilter = new BSensitiveWordsFilter(); + private CSensitiveWordsFilter cFilter = new CSensitiveWordsFilter(); + public String filterSensitiveWords(String text) { + String maskedText = aFilter.filterSexyWords(text); + maskedText = aFilter.filterPoliticalWords(maskedText); + maskedText = bFilter.filter(maskedText); + maskedText = cFilter.filter(maskedText, "***"); + return maskedText; + } +} + +// 使用适配器模式进行改造 +public interface ISensitiveWordsFilter { // 统一接口定义 + String filter(String text); +} +public class ASensitiveWordsFilterAdaptor implements ISensitiveWordsFilter { + private ASensitiveWordsFilter aFilter; + public String filter(String text) { + String maskedText = aFilter.filterSexyWords(text); + maskedText = aFilter.filterPoliticalWords(maskedText); + return maskedText; + } +} + +//...省略BSensitiveWordsFilterAdaptor、CSensitiveWordsFilterAdaptor... + +// 扩展性更好，更加符合开闭原则，如果添加一个新的敏感词过滤系统， +// 这个类完全不需要改动；而且基于接口而非实现编程，代码的可测试性更好。 +public class RiskManagement { + private List filters = new ArrayList<>(); + public void addSensitiveWordsFilter(ISensitiveWordsFilter filter) { + filters.add(filter); + } + public String filterSensitiveWords(String text) { + String maskedText = text; + for (ISensitiveWordsFilter filter : filters) { + maskedText = filter.filter(maskedText); + } + return maskedText; + } +} +``` +### 替换依赖的外部系统 +当我们把项目中依赖的一个外部系统替换为另一个外部系统的时候，利用适配器模式，可以减少对代码的改动。 + +``` +// 外部系统A +public interface IA { + //... + void fa(); +} +public class A implements IA { + //... + public void fa() { //... } +} + +// 在我们的项目中，外部系统A的使用示例 +public class Demo { + private IA a; + public Demo(IA a) { + this.a = a; + } + //... +} +Demo d = new Demo(new A()); + +// 将外部系统A替换成外部系统B +public class BAdaptor implemnts IA { + private B b; + public BAdaptor(B b) { + this.b= b; + } + public void fa() { + //... + b.fb(); + } +} +// 借助 BAdaptor，Demo 的代码中，调用 IA 接口的地方都无需改动， +// 只需要将BAdaptor如下注入到Demo即可。 +Demo d = new Demo(new BAdaptor(new B())); +``` + +### 兼容老版本 +在做版本升级的时候，对于一些要废弃的接口，我们不直接将其删除，而是暂时保留，并且标注为 deprecated，并将内部实现逻辑委托为新的接口实现。这样做的好处是，让使用它的项目有个过渡期，而不是强制进行代码修改。这也可以粗略地看作适配器模式的一个应用场景 + +### 适配不同格式的数据 +前面我们讲到，适配器模式主要用于接口的适配，实际上，它还可以用在不同格式的数据之间的适配。比如，把从不同征信系统拉取的不同格式的征信数据，统一为相同的格式，以方便存储和使用。再比如，Java 中的 Arrays.asList() 也可以看作一种数据适配器，将数组类型的数据转化为集合容器类型。 + +``` +List stooges = Arrays.asList("Larry", "Moe", "Curly"); +``` + +## 代理、桥接、装饰器、适配器 4 种设计模式的区别 +代理、桥接、装饰器、适配器，这 4 种模式是比较常用的结构型设计模式。它们的代码结构非常相似。笼统来说，它们都可以称为 Wrapper 模式，也就是通过 Wrapper 类二次封装原始类 + +尽管代码结构相似，但这 4 种设计模式的用意完全不同，也就是说要解决的问题、应用场景不同，这也是它们的主要区别 +- 代理模式：不改变原始类接口，为原始类定义一个代理类，主要的目的是为了访问控制，隔离原始代码。而非增加功能 +- 桥接模式：为了接口和实现分离，做到更好的解耦，可以让类更好、更容易的独立改变 +- 装饰器模式：在不改变类原始接口的情况下，对类的功能进行加强，并且支持多个装饰器的嵌套使用 +- 适配器模式：类似一个事后补救策略，提供跟原始类不同的接口，主要为了抹平不同接口的差异性，做到一致性。 + diff --git a/Chapter6 - Design Pattern/6.17.md b/Chapter6 - Design Pattern/6.17.md new file mode 100644 index 0000000..928742a --- /dev/null +++ b/Chapter6 - Design Pattern/6.17.md @@ -0,0 +1,58 @@ +# 门面模式 + +> 如何设计合理的接口粒度以兼顾接口的易用性和通用性 + +## 定义 +门面模式原理和实现都特别简单，应用场景也比较明确，主要在接口设计方面使用。 + +为了保证接口的可复用性（或者叫通用性），我们需要将接口尽量设计得细粒度一点，职责单一一点。但是，如果接口的粒度过小，在接口的使用者开发一个业务功能时，就会导致需要调用 n 多细粒度的接口才能完成。调用者肯定会抱怨接口不好用 + +反，如果接口粒度设计得太大，一个接口返回 n 多数据，要做 n 多事情，就会导致接口不够通用、可复用性不好。接口不可复用，那针对不同的调用者的业务需求，我们就需要开发不同的接口来满足，这就会导致系统的接口无限膨胀。解决方案就是门面模式 + + +门面模式，也叫外观模式，英文全称是 Facade Design Pattern。在 GoF 的《设计模式》一书中，门面模式是这样定义的 +> Provide a unified interface to a set of interfaces in a subsystem. Facade Pattern defines a higher-level interface that makes the subsystem easier to use. + +翻译成中文就是：门面模式为子系统提供一组统一的接口，定义一组高层接口让子系统更易用 + + +假设有一个系统 A，提供了 a、b、c、d 四个接口。系统 B 完成某个业务功能，需要调用 A 系统的 a、b、d 接口。利用门面模式，我们提供一个包裹 a、b、d 接口调用的门面接口 x，给系统 B 直接使用。 +不知道你会不会有这样的疑问，让系统 B 直接调用 a、b、d 感觉没有太大问题呀，为什么还要提供一个包裹 a、b、d 的接口 x 呢？ + +假设我们刚刚提到的系统 A 是一个后端服务器，系统 B 是 App 客户端。App 客户端通过后端服务器提供的接口来获取数据。我们知道，App 和服务器之间是通过移动网络通信的，网络通信耗时比较多，为了提高 App 的响应速度，我们要尽量减少 App 与服务器之间的网络通信次数。 + +假设，完成某个业务功能（比如显示某个页面信息）需要“依次”调用 a、b、d 三个接口，因自身业务的特点，不支持并发调用这三个接口。如果我们现在发现 App 客户端的响应速度比较慢，排查之后发现，是因为过多的接口调用过多的网络通信。针对这种情况，我们就可以利用门面模式，让后端服务器提供一个包裹 a、b、d 三个接口调用的接口 x。App 客户端调用一次接口 x，来获取到所有想要的数据，将网络通信的次数从 3 次减少到 1 次，也就提高了 App 的响应速度。 + +## 应用场景 +门面模式定义中的“子系统（subsystem）”也可以有多种理解方式。它既可以是一个完整的系统，也可以是更细粒度的类或者模块 + +### 解决易用性问题 +门面模式可以用来封装系统的底层实现，隐藏系统的复杂性，提供一组更加简单易用、更高层的接口。比如，Linux 系统调用函数就可以看作一种“门面”。它是 Linux 操作系统暴露给开发者的一组“特殊”的编程接口，它封装了底层更基础的 Linux 内核调用。再比如，Linux 的 Shell 命令，实际上也可以看作一种门面模式的应用。它继续封装系统调用，提供更加友好、简单的命令，让我们可以直接通过执行命令来跟操作系统交互。 + +设计原则、思想、模式很多都是相通的，是同一个道理不同角度的表述。实际上，从隐藏实现复杂性，提供更易用接口这个意图来看，门面模式有点类似之前讲到的迪米特法则（最少知识原则）和接口隔离原则：两个有交互的系统，只暴露有限的必要的接口。除此之外，门面模式还有点类似之前提到封装、抽象的设计思想，提供更抽象的接口，封装底层实现细节。 + +### 解决性能问题 +通过将多个接口调用替换为一个门面接口调用，减少网络通信成本，提高 App 客户端的响应速度。 + +讨论一下这样一个问题：从代码实现的角度来看，该如何组织门面接口和非门面接口？ +如果门面接口不多，我们完全可以将它跟非门面接口放到一块，也不需要特殊标记，当作普通接口来用即可。如果门面接口很多，我们可以在已有的接口之上，再重新抽象出一层，专门放置门面接口，从类、包的命名上跟原来的接口层做区分。如果门面接口特别多，并且很多都是跨多个子系统的，我们可以将门面接口放到一个新的子系统中 + +### 解决分布式事务问题 +在一个金融系统中，有两个业务领域模型，用户和钱包。这两个业务领域模型都对外暴露了一系列接口，比如用户的增删改查接口、钱包的增删改查接口。假设有这样一个业务场景：在用户注册的时候，我们不仅会创建用户（在数据库 User 表中），还会给用户创建一个钱 +包（在数据库的 Wallet 表中）。 + +对于这样一个简单的业务需求，我们可以通过依次调用用户的创建接口和钱包的创建接口来完成。但是，用户注册需要支持事务，也就是说，创建用户和钱包的两个操作，要么都成功，要么都失败，不能一个成功、一个失败。 + +要支持两个接口调用在一个事务中执行，是比较难实现的，这涉及分布式事务问题。虽然我们可以通过引入分布式事务框架或者事后补偿的机制来解决，但代码实现都比较复杂。而最简单的解决方案是，利用数据库事务或者 Spring 框架提供的事务（如果是 Java 语言的话），在一个事务中，执行创建用户和创建钱包这两个 SQL 操作。这就要求两个 SQL 操作要在一个接口中完成，所以，我们可以借鉴门面模式的思想，再设计一个包裹这两个操作的新接口，让新接口在一个事务中执行两个 SQL 操作。 + + +## 总结 +类、模块、系统之间的“通信”，一般都是通过接口调用来完成的。接口设计的好坏，直接影响到类、模块、系统是否好用。所以，我们要多花点心思在接口设计上。我经常说，完成接口设计，就相当于完成了一半的开发任务。只要接口设计得好，那代码就差不到哪里去 + +接口粒度设计得太大，太小都不好。太大会导致接口不可复用，太小会导致接口不易用。在实际的开发中，接口的可复用性和易用性需要“微妙”的权衡。针对这个问题，我的一个基本的处理原则是，尽量保持接口的可复用性，但针对特殊情况，允许提供冗余的门面接口，来提供更易用的接口 + + +## 思考 +适配器模式和门面模式（外观模式）的共同点都是将不好用的接口适配成好用的接口。那区别是什么？ +- 适配器模式强调的是接口转换，一些三方、二方设计不好的接口包装成符合设计预期的接口，解决的是原接口和目标接口不匹配的问题 +- 门面模式强调的是接口的设计，将几个小接口包装成一个大接口，方便调用（不用去关心那么多小接口），解决的是多接口调用的问题 \ No newline at end of file diff --git a/Chapter6 - Design Pattern/6.18.md b/Chapter6 - Design Pattern/6.18.md new file mode 100644 index 0000000..dd1dcaf --- /dev/null +++ b/Chapter6 - Design Pattern/6.18.md @@ -0,0 +1,172 @@ +# 组合模式 + +## 定义 +在 GoF 的《设计模式》一书中，组合模式是这样定义的： +> Compose objects into tree structure to represent part-whole hierarchies.Composite lets client treat individual objects and compositions of objects uniformly. +翻译成中文就是：将一组对象组织（Compose）成树形结构，以表示一种“部分 - 整体”的层次结构。组合让客户端（在很多设计模式书籍中，“客户端”代指代码的使用者。）可以统一单个对象和组合对象的处理逻辑 + +## 应用场景 + +假设我们有这样一个需求：设计一个类来表示文件系统中的目录，能方便地实现下面这些功 +能： +我们把文件和目录统一用 FileSystemNode 类来表示，并且通过 isFile 属性来区分。动态地添加、删除某个目录下的子目录或文件；统计指定目录下的文件个数；统计指定目录下的文件总大小。在下面的代码实现中，我们把文件和目录统一用 FileSystemNode 类来表示，并且通过 isFile 属性来区分 + +``` +public class FileSystemNode { + private String path; + private boolean isFile; + private List subNodes = new ArrayList<>(); + public FileSystemNode(String path, boolean isFile) { + this.path = path; + this.isFile = isFile; + } + public int countNumOfFiles() { + if (isFile) { + return 1; + } + int numOfFiles = 0; + for (FileSystemNode fileOrDir : subNodes) { + numOfFiles += fileOrDir.countNumOfFiles(); + } + return numOfFiles; + } + public long countSizeOfFiles() { + if (isFile) { + File file = new File(path); + if (!file.exists()) return 0; + return file.length(); + } + long sizeofFiles = 0; + for (FileSystemNode fileOrDir : subNodes) { + sizeofFiles += fileOrDir.countSizeOfFiles(); + } + return sizeofFiles; + } + public String getPath() { + return path; + } + public void addSubNode(FileSystemNode fileOrDir) { + subNodes.add(fileOrDir); + } + public void removeSubNode(FileSystemNode fileOrDir) { + int size = subNodes.size(); + int i = 0; + for (; i < size; ++i) { + if (subNodes.get(i).getPath().equalsIgnoreCase(fileOrDir.getPath())) { + break; + } + } + if (i < size) { + subNodes.remove(i); + } + } +} +``` + +单纯从功能实现角度来说，上面的代码没有问题，已经实现了我们想要的功能。但是，如果我们开发的是一个大型系统，从扩展性（文件或目录可能会对应不同的操作）、业务建模（文件和目录从业务上是两个概念）、代码的可读性（文件和目录区分对待更加符合人们对业务的认知）的角度来说，我们最好对文件和目录进行区分设计，定义为 File 和 Directory 两个类。 + +按照这个设计思路，我们对代码进行重构。重构之后的代码如下所示 + +``` +public abstract class FileSystemNode { + protected String path; + public FileSystemNode(String path) { + this.path = path; + } + public abstract int countNumOfFiles(); + public abstract long countSizeOfFiles(); + public String getPath() { + return path; + } +} +public class File extends FileSystemNode { + public File(String path) { + super(path); + } + @Override + public int countNumOfFiles() { + return 1; + } + @Override + public long countSizeOfFiles() { + java.io.File file = new java.io.File(path); + if (!file.exists()) return 0; + return file.length(); + } +} + +public class Directory extends FileSystemNode { + private List subNodes = new ArrayList<>(); + public Directory(String path) { + super(path); + } + @Override + public int countNumOfFiles() { + int numOfFiles = 0; + for (FileSystemNode fileOrDir : subNodes) { + numOfFiles += fileOrDir.countNumOfFiles(); + } + return numOfFiles; + } + @Override + public long countSizeOfFiles() { + long sizeofFiles = 0; + for (FileSystemNode fileOrDir : subNodes) { + sizeofFiles += fileOrDir.countSizeOfFiles(); + } + return sizeofFiles; + } + public void addSubNode(FileSystemNode fileOrDir) { + subNodes.add(fileOrDir); + } + public void removeSubNode(FileSystemNode fileOrDir) { + int size = subNodes.size(); + int i = 0; + for (; i < size; ++i) { + if (subNodes.get(i).getPath().equalsIgnoreCase(fileOrDir.getPath())) { + break; + } + } + if (i < size) { + subNodes.remove(i); + } + } +} +``` +文件和目录类都设计好了，我们来看，如何用它们来表示一个文件系统中的目录树结构。具体的代码示例如下所示 +``` +public class Demo { + public static void main(String[] args) { + Directory fileSystemTree = new Directory("/"); + Directory node_my = new Directory("/meiying/"); + Directory node_lbp = new Directory("/my/"); + fileSystemTree.addSubNode(node_lbp); + fileSystemTree.addSubNode(node_lbp); + File node_lbp_a = new File("/meiying/a.txt"); + File node_lbp_b = new File("/meiying/b.txt"); + Directory node_lbp_movies = new Directory("/meiying/movies/"); + node_lbp.addSubNode(node_lbp_a); + node_lbp.addSubNode(node_lbp_b); + node_lbp.addSubNode(node_lbp_movies); + File node_lbp_movies_c = new File("/meiying/movies/c.avi"); + node_lbp_movies.addSubNode(node_lbp_movies_c); + Directory node_lbp_docs = new Directory("/xzg/docs/"); + node_lbp.addSubNode(node_lbp_docs); + File node_lbp_docs_d = new File("/xzg/docs/d.txt"); + node_lbp_docs.addSubNode(node_lbp_docs_d); + System.out.println("/ files num:" + fileSystemTree.countNumOfFiles()); + System.out.println("/meiying/ files num:" + node_lbp.countNumOfFiles()); + } +} +``` +对照例子，重新审视下组合模式：将一组对象（文件和目录）组织成树形结构，以表示一种“部分-整体”的层次结构（目录与子目录的嵌套结构）。组合模 +式让客户端可以统一单个对象（文件）和组合对象（目录）的处理逻辑（递归遍历） + + +实际上，刚才讲的这种组合模式的设计思路，与其说是一种设计模式，倒不如说是对业务场景的一种数据结构和算法的抽象。其中，数据可以表示成树这种数据结构，业务需求可以通过在树上的递归遍历算法来实现。 + +## 思考 +组合模式的设计思路，与其说是一种设计模式，倒不如说是对业务场景的一种数据结构和算法的抽象。其中，数据可以表示成树这种数据结构，业务需求可以通过在树上的递归遍历算法来实现。 + +组合模式，将一组对象组织成树形结构，将单个对象和组合对象都看做树中的节点，以统一处理逻辑，并且它利用树形结构的特点，递归地处理每个子树，依次简化代码实现。使用组合模式的前提在于，你的业务场景必须能够表示成树形结构。所以，组合模式的应用场景也比较局限，它并不是一种很常用的设计模式。 + diff --git a/Chapter6 - Design Pattern/6.19.md b/Chapter6 - Design Pattern/6.19.md new file mode 100644 index 0000000..7e375de --- /dev/null +++ b/Chapter6 - Design Pattern/6.19.md @@ -0,0 +1,223 @@ +# 享元模式 + +## 定义 +“享元”，顾名思义就是被共享的单元。享元模式的意图是复用对象，节省内存，前提是享元对象是不可变对象。 + +当一个系统中存在大量重复对象的时候，如果这些重复的对象是不可变对象，我们就可以利用享元模式将对象设计成享元，在内存中只保留一份实例，供多处代码引用。这样可以减少内存中对象的数量，起到节省内存的目的。实际上，不仅仅相同对象可以设计成享元，对于相似对象，我们也可以将这些对象中相同的部分（字段）提取出来，设计成享元，让这些大量相似对象引用这些享元。 + +不可变对象”指的是，一旦通过构造函数初始化完成之后，它的状态（对象的成员变量或者属性）就不会再被修改了。所以，不可变对象不能暴露任何 set() 等修改内部状态的方法。之所以要求享元是不可变对象，那是因为它会被多处代码共享使用，避免一处代码对享元进行了修改，影响到其他使用它的代码。 + +## 实现 +享元模式的代码实现非常简单，主要是通过工厂模式，在工厂类中，通过一个 Map 或者 List 来缓存已经创建好的享元对象，以达到复用的目的 + +假设我们在开发一个棋牌游戏（比如象棋）。一个游戏厅中有成千上万个“房间”，每个房间对应一个棋局。棋局要保存每个棋子的数据，比如：棋子类型（将、相、士、炮等）、棋子颜色（红方、黑方）、棋子在棋局中的位置。利用这些数据，我们就能显示一个完整的棋盘给玩家。具体的代码如下所示。其中，ChessPiece 类表示棋子，ChessBoard 类表示一个棋局，里面保存了象棋中 30 个棋子的信息 +``` +public class ChessPiece {//棋子 + private int id; + private String text; + private Color color; + private int positionX; + private int positionY; + public ChessPiece(int id, String text, Color color, int positionX, int position) { + this.id = id; + this.text = text; + this.color = color; + this.positionX = positionX; + this.positionY = positionX; + } + + public static enum Color { + RED, BLACK + } + // ...省略其他属性和getter/setter方法... +} + +public class ChessBoard {//棋局 + private Map chessPieces = new HashMap<>(); + public ChessBoard() { + init(); + } + private void init() { + chessPieces.put(1, new ChessPiece(1, "車", ChessPiece.Color.BLACK, 0, 0)); + chessPieces.put(2, new ChessPiece(2,"馬", ChessPiece.Color.BLACK, 0, 1)); + //...省略摆放其他棋子的代码... + } + public void move(int chessPieceId, int toPositionX, int toPositionY) { + //...省略... + } +} +``` +为了记录每个房间当前的棋局情况，我们需要给每个房间都创建一个 ChessBoard 棋局对象。因为游戏大厅中有成千上万的房间（实际上，百万人同时在线的游戏大厅也有很多），那保存这么多棋局对象就会消耗大量的内存。有没有什么办法来节省内存呢？这个时候，享元模式就可以派上用场了。像刚刚的实现方式，在内存中会有大量的相似对象。这些相似对象的 id、text、color 都是相同的，唯独 positionX、positionY 不同。实际上，我们可以将棋子的 id、text、color 属性拆分出来，设计成独立的类，并且作为享元供多个棋盘复用。这样，棋盘只需要记录每个棋子的位置信息就可以了。具体的代码实现如下所示 +``` +// 享元类 +public class ChessPieceUnit { + private int id; + private String text; + private Color color; + public ChessPieceUnit(int id, String text, Color color) { + this.id = id; + this.text = text; + this.color = color; + } + public static enum Color { + RED, BLACK + } + // ...省略其他属性和getter方法... +} + +public class ChessPieceUnitFactory { + private static final Map pieces = new HashMap<>(); + static { + pieces.put(1, new ChessPieceUnit(1, "車", ChessPieceUnit.Color.BLACK)); + pieces.put(2, new ChessPieceUnit(2,"馬", ChessPieceUnit.Color.BLACK)); + //...省略摆放其他棋子的代码... + } + public static ChessPieceUnit getChessPiece(int chessPieceId) { + return pieces.get(chessPieceId); + } +} + +public class ChessPiece { + private ChessPieceUnit chessPieceUnit; + private int positionX; + private int positionY; + public ChessPiece(ChessPieceUnit unit, int positionX, int positionY) { + this.chessPieceUnit = unit; + this.positionX = positionX; + this.positionY = positionY; + } + // 省略getter、setter方法 +} +public class ChessBoard { + private Map chessPieces = new HashMap<>(); + public ChessBoard() { + init(); + } + private void init() { + chessPieces.put(1, new ChessPiece( + ChessPieceUnitFactory.getChessPiece(1), 0,0)); + chessPieces.put(1, new ChessPiece( + ChessPieceUnitFactory.getChessPiece(2), 1,0)); + //...省略摆放其他棋子的代码... + } + public void move(int chessPieceId, int toPosintionX, int toPositionY) { + // ... + } +} +``` + +在上面的代码实现中，我们利用工厂类来缓存 ChessPieceUnit 信息（也就是 id、text、color）。通过工厂类获取到的 ChessPieceUnit 就是享元。所有的 ChessBoard 对象共享这 30 个 ChessPieceUnit 对象（因为象棋中只有 30 个棋子）。在使用享元模式之前，记录 1 万个棋局，我们要创建 30 万（30*1 万）个棋子的 ChessPieceUnit 对象。利用享元模式，我们只需要创建 30 个享元对象供所有棋局共享使用即可，大大节省了内存。 + +那享元模式的原理讲完了，我们来总结一下它的代码结构。实际上，它的代码实现非常简单，主要是通过工厂模式，在工厂类中，通过一个 Map 来缓存已经创建过的享元对象，来达到复用的目的。 + + +## 场景 +### 享元模式在 Java Integer 中的应用 +``` +Integer i1 = 56; +Integer i2 = 56; +Integer i3 = 129; +Integer i4 = 129; +System.out.println(i1 == i2); // true +System.out.println(i3 == i4); // false +``` +如果不熟悉 Java 语言，你可能会觉得，i1 和 i2 值都是 56，i3 和 i4 值都是 129，i1 跟 i2 值相等，i3 跟 i4 值相等，所以输出结果应该是两个 true。这样的分析是不对的，主要还是因为你对 Java 语法不熟悉。要正确地分析上面的代码，我们需要弄清楚下面两个问题 + +如何判定两个 Java 对象是否相等（也就代码中的“==”操作符的含义）？什么是自动装箱（Autoboxing）和自动拆箱（Unboxing）？ + +所谓的自动装箱，就是自动将基本数据类型转换为包装器类型。所谓的自动拆箱，也就是自动将包装器类型转化为基本数据类型。具体的代码示例如下所示： +``` +Integer i = 56; //自动装箱 +int j = i; //自动拆箱 +``` +数值 56 是基本数据类型 int，当赋值给包装器类型（Integer）变量的时候，触发自动装箱操作，创建一个 Integer 类型的对象，并且赋值给变量 i。其底层相当于执行了下面这条语句： +``` +Integer i = 59；底层执行了：Integer i = Integer.valueOf(59); +``` +反过来，当把包装器类型的变量 i，赋值给基本数据类型变量 j 的时候，触发自动拆箱操作，将 i 中的数据取出，赋值给 j。其底层相当于执行了下面这条语句： +``` +int j = i; 底层执行了：int j = i.intValue(); +``` +弄清楚了自动装箱和自动拆箱，我们再来看，如何判定两个对象是否相等？不过，在此之前，我们先要搞清楚，Java 对象在内存中是如何存储的。我们通过下面这个例子来说明一下。 +``` +User a = new User(123, 23); // id=123, age=23 +``` +a 存储的值是 User 对象的内存地址，a 是一个指针，a 的值就是对象的地址值。 + +当我们通过“==”来判定两个对象是否相等的时候，实际上是在判断两个局部变量存储的地址是否相同，换句话说，是在判断两个局部变量是否指向相同的对象。 + +前 4 行赋值语句都会触发自动装箱操作，也就是会创建 Integer 对象并且赋值给 i1、i2、i3、i4 这四个变量。根据刚刚的讲解，i1、i2 尽管存储的数值相同，都是 56，但是指向不同的 Integer 对象，所以通过“==”来判定是否相同的时候，会返回 false。同理，i3==i4 判定语句也会返回 false + + +不过，上面的分析还是不对，答案并非是两个 false，而是一个 true，一个 false。看到这里，你可能会比较纳闷了。实际上，这正是因为 Integer 用到了享元模式来复用对象，才导致了这样的运行结果。当我们通过自动装箱，也就是调用 valueOf() 来创建 Integer 对象的时候，如果要创建的 Integer 对象的值在 -128 到 127 之间，会从 IntegerCache 类中直接返回，否则才调用 new 方法创建。看代码更加清晰一些，Integer 类的 valueOf() 函数的具体代码如下所示 +``` +public static Integer valueOf(int i) { + if (i >= IntegerCache.low && i <= IntegerCache.high) + return IntegerCache.cache[i + (-IntegerCache.low)]; + return new Integer(i); +} +``` +实际上，这里的 IntegerCache 相当于，我们上一节课中讲的生成享元对象的工厂类，只不过名字不叫 xxxFactory 而已。我们来看它的具体代码实现。这个类是 Integer 的内部类，你也可以自行查看 JDK 源码 +``` +** +* Cache to support the object identity semantics of autoboxing for values betw +* -128 and 127 (inclusive) as required by JLS. +* +* The cache is initialized on first usage. The size of the cache +* may be controlled by the {@code -XX:AutoBoxCacheMax=} option. +* During VM initialization, java.lang.Integer.IntegerCache.high property +* may be set and saved in the private system properties in the +* sun.misc.VM class. +*/ +private static class IntegerCache { + static final int low = -128; + static final int high; + static final Integer cache[]; + static { + // high value may be configured by property + int h = 127; + String integerCacheHighPropValue = + sun.misc.VM.getSavedProperty("java.lang.Integer.IntegerCache.high") + if (integerCacheHighPropValue != null) { + try { + int i = parseInt(integerCacheHighPropValue); + i = Math.max(i, 127); + // Maximum array size is Integer.MAX_VALUE + h = Math.min(i, Integer.MAX_VALUE - (-low) -1); + } catch( NumberFormatException nfe) { + // If the property cannot be parsed into an int, ignore it. + } + } + high = h; + cache = new Integer[(high - low) + 1]; + int j = low; + for(int k = 0; k < cache.length; k++) + cache[k] = new Integer(j++); + // range [-128, 127] must be interned (JLS7 5.1.7) + assert IntegerCache.high >= 127; + } + private IntegerCache() {} +} +``` +回到问题，56处于-128和127之间，i1 和 i2 会指向相同的享元对象，所以第一个为 true，而129大于127，不会被缓存，所以每次都是一个新的对象，也就是i3和i4指向2个不同的 Integer 对象，所以第二个为 false。 + + +## 对比 +在上面的讲解中，我们多次提到“共享”“缓存”“复用”这些字眼，那它跟单例、缓存、对象池这些概念有什么区别呢？ + +### 享元模式跟单例的区别 +在单例模式中，一个类只能创建一个对象，而在享元模式中，一个类可以创建多个对象，每个对象被多处代码引用共享。实际上，享元模式有点类似于之前讲到的单例的变体：多例。 + +我们前面也多次提到，区别两种设计模式，不能光看代码实现，而是要看设计意图，也就是要解决的问题。尽管从代码实现上来看，享元模式和多例有很多相似之处，但从设计意图上来看，它们是完全不同的。应用享元模式是为了对象复用，节省内存，而应用多例模式是为了限制对象的个数 + +### 享元模式跟缓存的区别 +在享元模式的实现中，我们通过工厂类来“缓存”已经创建好的对象。这里的“缓存”实际上是“存储”的意思，跟我们平时所说的“数据库缓存”“CPU 缓存”“MemCache 缓存”是两回事。我们平时所讲的缓存，主要是为了提高访问效率，而非复用 + +### 享元模式跟对象池的区别 +你可能对连接池、线程池比较熟悉，对对象池比较陌生，所以，这里我简单解释一下对象池。像 C++ 这样的编程语言，内存的管理是由程序员负责的。为了避免频繁地进行对象创建和释放导致内存碎片，我们可以预先申请一片连续的内存空间，也就是这里说的对象池。每次创建对象时，我们从对象池中直接取出一个空闲对象来使用，对象使用完成之后，再放回到对象池中以供后续复用，而非直接释放掉。 + +虽然对象池、连接池、线程池、享元模式都是为了复用，但是，如果我们再细致地抠一抠“复用”这个字眼的话，对象池、连接池、线程池等池化技术中的“复用”和享元模式中的“复用”实际上是不同的概念。 + +池化技术中的“复用”可以理解为“重复使用”，主要目的是节省时间（比如从数据库池中取一个连接，不需要重新创建）。在任意时刻，每一个对象、连接、线程，并不会被多处使用，而是被一个使用者独占，当使用完成之后，放回到池中，再由其他使用者重复利用。享元模式中的“复用”可以理解为“共享使用”，在整个生命周期中，都是被所有使用者共享的，主要目的是节省空间。 + + diff --git a/Chapter6 - Design Pattern/6.2.md b/Chapter6 - Design Pattern/6.2.md new file mode 100644 index 0000000..3f8b414 --- /dev/null +++ b/Chapter6 - Design Pattern/6.2.md @@ -0,0 +1,162 @@ +# 面向对象 + + +## 封装、抽象、继承、多态分别可以解决什么编程问题 + +### 封装 +封装也叫作信息隐藏或者数据访问保护。类通过暴露有限的访问接口，授权外部仅能通过类提供的方式（或者叫函数）来访问内部信息或者数据。 + +对于封装这个特性，我们需要编程语言本身提供一定的语法机制来支持。这个语法机制就是访问权限控制。private、public 等关键字就是 Java 语言中的访问权限控制语法。private 关键字修饰的属性只能类本身访问，可以保护其不被类之外的代码直接访问。如果 Java 语言没有提供访问权限控制语法，所有的属性默认都是 public 的，那任意外部代码都可以通过类似 wallet.id=123; 这样的方式直接访问、修改属性，也就没办法达到隐藏信息和保护数据的目的了，也就无法支持封装特性了。 + +如果我们对类中属性的访问不做限制，那任何代码都可以访问、修改类中的属性，虽然这样看起来更加灵活，但从另一方面来说，过度灵活也意味着不可控，属性可以随意被以各种奇葩的方式修改，而且修改逻辑可能散落在代码中的各个角落，势必影响代码的可读性、可维护性。 + +除此之外，类仅仅通过有限的方法暴露必要的操作，也能提高类的易用性。如果我们把类属性都暴露给类的调用者，调用者想要正确地操作这些属性，就势必要对业务细节有足够的了解。而这对于调用者来说也是一种负担。相反，如果我们将属性封装起来，暴露少许的几个必要的方法给调用者使用，调用者就不需要了解太多背后的业务细节，用错的概率就减少很多。这就好比，如果一个冰箱有很多按钮，你就要研究很长时间，还不一定能操作正确。相反，如果只有几个必要的按钮，比如开、停、调节温度，你一眼就能知道该如何来操作，而且操作出错的概率也会降低很多。（迪米特法则、最小知识原则） + + +### 抽象 +封装主要讲的是如何隐藏信息、保护数据，而抽象讲的是如何隐藏方法的具体实现，让调用者只需要关心方法提供了哪些功能，并不需要知道这些功能是如何实现的。 + +在面向对象编程中，我们常借助编程语言提供的接口类（比如 Java 中的 interface 关键字语法）或者抽象类（比如 Java 中的 abstract 关键字语法）这两种语法机制，来实现抽象这一特性。 + +换一个角度来考虑，我们在定义（或者叫命名）类的方法的时候，也要有抽象思维，不要在方法定义中，暴露太多的实现细节，以保证在某个时间点需要改变方法的实现逻辑的时候，不用去修改其定义。举个简单例子，比如 getAliyunPictureUrl() 就不是一个具有抽象思维的命名，因为某一天如果我们不再把图片存储在阿里云上，而是存储在私有云上，那这个命名也要随之被修改。相反，如果我们定义一个比较抽象的函数，比如叫作 getPictureUrl()，那即便内部存储方式修改了，我们也不需要修改命名。 + +客户端 SDK 在设计对外暴露的属性的时候，也遵循这个原则，对外提供通用的 api 协议，而不是具体的方法，后期业务变动或者底层实现在做替换的时候，不需要改方法名，对调用者的影响最小。 + +### 继承 +继承是用来表示类之间的 is-a 关系，比如猫是一种哺乳动物。从继承关系上来讲，继承可以分为两种模式，单继承和多继承。单继承表示一个子类只继承一个父类，多继承表示一个子类可以继承多个父类，比如猫既是哺乳动物，又是爬行动物 + +继承最大的一个好处就是代码复用。假如两个类有一些相同的属性和方法，我们就可以将这些相同的部分，抽取到父类中，让两个子类继承父类。这样，两个子类就可以重用父类中的代码，避免代码重复写多遍。 + +某些编程语言不支持多重继承的原因？具有副作用，菱形继承问题（钻石问题、决议问题、二义性问题） +假设类 B、类C继承自类 A，且都重写了类 A 的同一个方法，而类 D 同时继承了类B、类C，那么此时类 D 会继承类B、C重写的A的方法，类D会选择继承哪一个呢？会产生歧义。Java8 的 interface 可以有默认方法实现，曲线救国。 + +Objective-C 没有多继承。为什么？如何实现？ +消息机制名字查找发生在运行时而非编译时，很难解决多个基类可能导致的二义性问题 + +可以利用以下方式实现多继承 +- 组合 +- 协议 +- Category +- Runtime 消息转发 +- NSProxy + +### 多态 +多态是指，子类可以替换父类，在实际的代码运行过程中，调用子类的方法实现。多态可以提高代码可拓展性和复用性。 + + +## 基于接口而非实现编程 +越抽象、越顶层、越脱离具体某一实现的设计，越能提高代码的灵活性，越能应对未来的需求变化。好的代码设计，不仅能应对当下的需求，而且在将来需求发生变化的时候，仍然能够在不破坏原有代码设计的情况下灵活应对。 + +什么情况下需要思考设计接口？ +这条原则的设计初衷是，将接口和实现相分离，封装不稳定的实现，暴露稳定的接口。上游系统面向接口而非实现编程，不依赖不稳定的实现细节，这样当实现发生变化的时候，上游系统的代码基本上不需要做改动，以此来降低代码间的耦合性，提高代码的扩展性。 + +从这个设计初衷上来看，如果在我们的业务场景中，某个功能只有一种实现方式，未来也不可能被其他实现方式替换，那我们就没有必要为其设计接口，也没有必要基于接口编程，直接使用实现类就可以了。 + +除此之外，越是不稳定的系统，我们越是要在代码的扩展性、维护性上下功夫。相反，如果某个系统特别稳定，在开发完之后，基本上不需要做维护，那我们就没有必要为其扩展性， + + +## 多用组合少用继承？ +继承是面向对象的四大特性之一，用来表示类之间的 is-a 关系，可以解决代码复用的问题。虽然继承有诸多作用，但继承层次过深、过复杂，也会影响到代码的可维护性。 + +举个例子 + +假设我们要设计一个关于鸟的类。我们将“鸟类”这样一个抽象的事物概念，定义为一个抽象类 AbstractBird。所有更细分的鸟，比如麻雀、鸽子、乌鸦等，都继承这个抽象类。 + +我们知道，大部分鸟都会飞，那我们可不可以在 AbstractBird 抽象类中，定义一个 fly() 方法呢？答案是否定的。尽管大部分鸟都会飞，但也有特例，比如鸵鸟就不会飞。鸵鸟继承具有 fly() 方法的父类，那鸵鸟就具有“飞”这样的行为，这显然不符合我们对现实世界中事物的认识。当然，你可能会说，我在鸵鸟这个子类中重写（override）fly() 方法，让它抛出 UnSupportedMethodException 异常不就可以了吗？具体的代码实现如下所示 + +``` +public class AbstractBird { +//... 省略其他属性和方法... +public void fly() { //... } +} + +public class Ostrich extends AbstractBird { // 鸵鸟 + //... 省略其他属性和方法... + public void fly() { + throw new UnSupportedMethodException("I can't fly.'"); + } +} +``` + +这种设计思路虽然可以解决问题，但不够优美。因为除了鸵鸟之外，不会飞的鸟还有很多，比如企鹅。对于这些不会飞的鸟来说，我们都需要重写 fly() 方法，抛出异常。这样的设计，一方面，徒增了编码的工作量；另一方面，也违背了我们之后要讲的最小知识原则（Least Knowledge Principle，也叫最少知识原则或者迪米特法则），暴露不该暴露的接口给外部，增加了类使用过程中被误用的概率。 + +你可能又会说，那我们再通过 AbstractBird 类派生出两个更加细分的抽象类：会飞的鸟类 AbstractFlyableBird 和不会飞的鸟类 AbstractUnFlyableBird，让麻雀、乌鸦这些会飞的鸟都继承 AbstractFlyableBird，让鸵鸟、企鹅这些不会飞的鸟，都继承 AbstractUnFlyableBird 类，不就可以了吗？具体的继承关系如下图所示： +![](./../assets/oop-mixBetterThanSuper.png) + + +从图中我们可以看出，继承关系变成了三层。不过，整体上来讲，目前的继承关系还比较简单，层次比较浅，也算是一种可以接受的设计思路。我们再继续加点难度。在刚刚这个场景中，我们只关注“鸟会不会飞”，但如果我们还关注“鸟会不会叫”，那这个时候，我们又该如何设计类之间的继承关系呢？ + +是否会飞？是否会叫？两个行为搭配起来会产生四种情况：会飞会叫、不会飞会叫、会飞不会叫、不会飞不会叫。如果我们继续沿用刚才的设计思路，那就需要再定义四个抽象类（AbstractFlyableTweetableBird、AbstractFlyableUnTweetableBird、AbstractUnFlyableTweetableBird、AbstractUnFlyableUnTweetableBird）。 + +会不会下蛋、会不会打猎，是不是组合就爆炸了？ +总之，继承最大的问题就在于：继承层次过深、继承关系过于复杂会影响到代码的可读性和可维护性。这也是为什么业界不推荐使用继承而推荐组合。 + +实际上，我们可以利用组合（composition）、接口、委托（delegation）三个技术手段，一块儿来解决刚刚继承存在的问题。 + +我们前面讲到接口的时候说过，接口表示具有某种行为特性。针对“会飞”这样一个行为特性，我们可以定义一个 Flyable 接口，只让会飞的鸟去实现这个接口。对于会叫、会下蛋这些行为特性，我们可以类似地定义 Tweetable 接口、EggLayable 接口。我们将这个设计思路翻译成 Java 代码的话，就是下面这个样子 +``` +public interface Flyable { + void fly(); +} +public interface Tweetable { + void tweet(); +} +public interface EggLayable { + void layEgg(); +} +public class Ostrich implements Tweetable, EggLayable {// 鸵鸟 + //... 省略其他属性和方法... + @Override + public void tweet() { //... } + @Override + public void layEgg() { //... } +} +public class Sparrow impelents Flayable, Tweetable, EggLayable {// 麻雀 + //... 省略其他属性和方法... + @Override + public void fly() { //... } + @Override + public void tweet() { //... } + @Override + public void layEgg() { //... } +} +``` + +不过，我们知道，接口只声明方法，不定义实现。也就是说，每个会下蛋的鸟都要实现一遍 layEgg() 方法，并且实现逻辑是一样的，这就会导致代码重复的问题。那这个问题又该如何解决呢？ + +我们可以针对三个接口再定义三个实现类，它们分别是：实现了 fly() 方法的 FlyAbility 类、实现了 tweet() 方法的 TweetAbility 类、实现了 layEgg() 方法的 EggLayAbility 类。 然后，通过组合和委托技术来消除代码重复。具体的代码实现如下所示： + +``` +public interface Flyable { + void fly()； +} + +public class FlyAbility implements Flyable { + @Override + public void fly() { //... } +} + +// 省略 Tweetable/TweetAbility/EggLayable/EggLayAbility +public class Ostrich implements Tweetable, EggLayable {// 鸵鸟 + private TweetAbility tweetAbility = new TweetAbility(); // 组合 + private EggLayAbility eggLayAbility = new EggLayAbility(); // 组合 + + //... 省略其他属性和方法... + @Override + public void tweet() { + tweetAbility.tweet(); // 委托 + } + + @Override + public void layEgg() { + eggLayAbility.layEgg(); // 委托 + } +} +``` +我们知道继承主要有三个作用：表示 is-a 关系，支持多态特性，代码复用。而这三个作用都可以通过其他技术手段来达成。比如 is-a 关系，我们可以通过组合和接口的 has-a 关系来替代；多态特性我们可以利用接口来实现；代码复用我们可以通过组合和委托来实现。所以，从理论上讲，通过组合、接口、委托三个技术手段，我们完全可以替换掉继承，在项目中不用或者少用继承关系，特别是一些复杂的继承关系。 + + +如何判断该用组合还是继承？ +尽管我们鼓励多用组合少用继承，但组合也并不是完美的，继承也并非一无是处。在实际的项目开发中，我们还是要根据具体的情况，来选择该用继承还是组合。如果类之间的继承结构稳定，层次比较浅，关系不复杂，我们就可以大胆地使用继承。反之，我们就尽量使用组合来替代继承。除此之外，还有一些设计模式、特殊的应用场景，会固定使用继承或者组合。 + + diff --git a/Chapter6 - Design Pattern/6.20.md b/Chapter6 - Design Pattern/6.20.md new file mode 100644 index 0000000..47ccd4e --- /dev/null +++ b/Chapter6 - Design Pattern/6.20.md @@ -0,0 +1,486 @@ +# 观察者模式 + +> 我们常把 23 种经典的设计模式分为三类：创建型、结构型、行为型。前面我们已经学习了创建型和结构型，从今天起，我们开始学习行为型设计模式。我们知道，创建型设计模式主要解决“对象的创建”问题，结构型设计模式主要解决“类或对象的组合或组装”问题，那行为型设计模式主要解决的就是“类或对象之间的交互”问题。 + +## 定义 +观察者模式（Observer Design Pattern）也被称为发布订阅模式（Publish-Subscribe Design Pattern）。在 GoF 的《设计模式》一书中，它的定义是这样的 +> Define a one-to-many dependency between objects so that when one object changes state, all its dependents are notified and updated automatically. +在对象之间定义一个一对多的依赖，当一个对象状态改变的时候，所有依赖的对象都会自动收到通知。 + +实际上，观察者模式是一个比较抽象的模式，根据不同的应用场景和需求，有完全不同的实现方式，待会我们会详细地讲到。现在，我们先来看其中最经典的一种实现方式。这也是在讲到这种模式的时候，很多书籍或资料给出的最常见的实现方式。具体的代码如下所示： + +``` +public interface Subject { + void registerObserver(Observer observer); + void removeObserver(Observer observer); + void notifyObservers(Message message); +} + +public interface Observer { + void update(Message message); +} + +public class ConcreteSubject implements Subject { + private List observers = new ArrayList(); + @Override + public void registerObserver(Observer observer) { + observers.add(observer); + } + @Override + public void removeObserver(Observer observer) { + observers.remove(observer); + } + @Override + public void notifyObservers(Message message) { + for (Observer observer : observers) { + observer.update(message); + } + } +} + +public class ConcreteObserverOne implements Observer { + @Override + public void update(Message message) { + //TODO: 获取消息通知，执行自己的逻辑... + System.out.println("ConcreteObserverOne is notified."); + } +} +public class ConcreteObserverTwo implements Observer { + @Override + public void update(Message message) { + //TODO: 获取消息通知，执行自己的逻辑... + System.out.println("ConcreteObserverTwo is notified."); + } +} +public class Demo { + public static void main(String[] args) { + ConcreteSubject subject = new ConcreteSubject(); + subject.registerObserver(new ConcreteObserverOne()); + subject.registerObserver(new ConcreteObserverTwo()); + subject.notifyObservers(new Message()); + } +} +``` +实际上，上面的代码算是观察者模式的“模板代码”，只能反映大体的设计思路。在真实的软件开发中，并不需要照搬上面的模板代码。观察者模式的实现方法各式各样，函数、类的命名等会根据业务场景的不同有很大的差别，比如 register 函数还可以叫作 attach， remove 函数还可以叫作 detach 等等。不过，万变不离其宗，设计思路都是差不多的。 + +## 场景 + +假设我们在开发一个 P2P 投资理财系统，用户注册成功之后，我们会给用户发放投资体验金。代码实现大致是下面这个样子的： +``` +public class UserController { + private UserService userService; // 依赖注入 + private PromotionService promotionService; // 依赖注入 + public Long register(String telephone, String password) { + //省略输入参数的校验代码 + //省略userService.register()异常的try-catch代码 + long userId = userService.register(telephone, password); + promotionService.issueNewUserExperienceCash(userId); + return userId; + } +} +``` +虽然注册接口做了两件事情，注册和发放体验金，违反单一职责原则，但是，如果没有扩展和修改的需求，现在的代码实现是可以接受的。如果非得用观察者模式，就需要引入更多的类和更加复杂的代码结构，反倒是一种过度设计。 + +相反，如果需求频繁变动，比如，用户注册成功之后，不再发放体验金，而是改为发放优惠券，并且还要给用户发送一封“欢迎注册成功”的站内信。这种情况下，我们就需要频繁地修改 register() 函数中的代码，违反开闭原则。而且，如果注册成功之后需要执行的后续操作越来越多，那 register() 函数的逻辑会变得越来越复杂，也就影响到代码的可读性和可维护性 + +用观察者模式进行改造 +``` +public interface RegObserver { + void handleRegSuccess(long userId); +} +public class RegPromotionObserver implements RegObserver { + private PromotionService promotionService; // 依赖注入 + @Override + public void handleRegSuccess(long userId) { + promotionService.issueNewUserExperienceCash(userId); + } +} +public class RegNotificationObserver implements RegObserver { + private NotificationService notificationService; + @Override + public void handleRegSuccess(long userId) { + notificationService.sendInboxMessage(userId, "Welcome..."); + } +} +public class UserController { + private UserService userService; // 依赖注入 + private List regObservers = new ArrayList<>(); + // 一次性设置好，之后也不可能动态的修改 + public void setRegObservers(List observers) { + regObservers.addAll(observers); + } + public Long register(String telephone, String password) { + //省略输入参数的校验代码 + //省略userService.register()异常的try-catch代码 + long userId = userService.register(telephone, password); + for (RegObserver observer : regObservers) { + observer.handleRegSuccess(userId); + } + return userId; + } +} +``` +当我们需要添加新的观察者的时候，比如，用户注册成功之后，推送用户注册信息给大数据征信系统，基于观察者模式的代码实现，UserController 类的 register() 函数完全不需要修改，只需要再添加一个实现了 RegObserver 接口的类，并且通过 setRegObservers()函数将它注册到 UserController 类中即可 + +当我们把发送体验金替换为发送优惠券的时候，需要修改 RegPromotionObserver 类中 handleRegSuccess() 函数的代码，这还是违反开闭原则呀？你说得没错，不过，相对于 register() 函数来说，handleRegSuccess() 函数的逻辑要简单很多，修改更不容易出错，引入 bug 的风险更低。 + +**设计模式要干的事情就是解耦。创建型模式是将创建和使用代码解耦，结构型模式是将不同功能代码解耦，行为型模式是将不同的行为代码解耦，具体到观察者模式，它是将观察者和被观察者代码解耦。借助设计模式，我们利用更好的代码结构，将一大坨代码拆分成职责更单一的小类，让其满足开闭原则、高内聚松耦合等特性，以此来控制和应对代码的复杂性，提高代码的可扩展性**。 + + +## 实现方式 +观察者模式的应用场景非常广泛，小到代码层面的解耦，大到架构层面的系统解耦，再或者一些产品的设计思路，都有这种模式的影子，比如，邮件订阅、RSS Feeds，本质上都是观察者模式 + +不同的应用场景和需求下，这个模式也有截然不同的实现方式，开篇的时候我们也提到，有同步阻塞的实现方式，也有异步非阻塞的实现方式；有进程内的实现方式，也有跨进程的实现方式 + +之前讲到的实现方式，从刚刚的分类方式上来看，它是一种同步阻塞的实现方式。观察者和被观察者代码在同一个线程内执行，被观察者一直阻塞，直到所有的观察者代码都执行完成之后，才执行后续的代码。对照上面讲到的用户注册的例子，register() 函数依次调用执行每个观察者的 handleRegSuccess() 函数，等到都执行完成之后，才会返回结果给客户端。 + +如果注册接口是一个调用比较频繁的接口，对性能非常敏感，希望接口的响应时间尽可能短，那我们可以将同步阻塞的实现方式改为异步非阻塞的实现方式，以此来减少响应时间。具体来讲，当 userService.register() 函数执行完成之后，我们启动一个新的线程来执行观察者的 handleRegSuccess() 函数，这样userController.register() 函数就不需要等到所有的 handleRegSuccess() 函数都执行完成之后才返回结果给客户端。userController.register() 函数从执行 3 个 SQL 语句才返回，减少到只需要执行 1 个 SQL 语句就返回，响应时间粗略来讲减少为原来的 1/3。 + +如何实现一个异步非阻塞的观察者模式呢？简单做法有两种实现方式。其中一种是：在每个 handleRegSuccess() 函数中创建一个新的线程执行代码逻辑；另一种是：在 UserController 的 register() 函数中使用线程池来执行每个观察者的 handleRegSuccess() 函数。两种实现方式的具体代码如下所示 +``` +// 第一种实现方式，其他类代码不变，就没有再重复罗列 +public class RegPromotionObserver implements RegObserver { + private PromotionService promotionService; // 依赖注入 + @Override + public void handleRegSuccess(long userId) { + Thread thread = new Thread(new Runnable() { + @Override + public void run() { + promotionService.issueNewUserExperienceCash(userId); + } + }); + thread.start(); + } +} + +// 第二种实现方式，其他类代码不变，就没有再重复罗列 +public class UserController { + private UserService userService; // 依赖注入 + private List regObservers = new ArrayList<>(); + private Executor executor; + public UserController(Executor executor) { + this.executor = executor; + } + public void setRegObservers(List observers) { + regObservers.addAll(observers); + } + public Long register(String telephone, String password) { + //省略输入参数的校验代码 + //省略userService.register()异常的try-catch代码 + long userId = userService.register(telephone, password); + for (RegObserver observer : regObservers) { + executor.execute(new Runnable() { + @Override + public void run() { + observer.handleRegSuccess(userId); + } + }); + } + return userId; + } +} +``` +对于第一种实现方式，频繁地创建和销毁线程比较耗时，并且并发线程数无法控制，创建过多的线程会导致堆栈溢出。第二种实现方式，尽管利用了线程池解决了第一种实现方式的问题，但线程池、异步执行逻辑都耦合在了 register() 函数中，增加了这部分业务代码的维护成本。 + +框架的作用有：隐藏实现细节，降低开发难度，做到代码复用，解耦业务与非业务代码，让程序员聚焦业务开发。针对异步非阻塞观察者模式，我们也可以将它抽象成框架来达到这样的效果，而这个框架就是接下来要研究的 EventBus（借鉴 Google Guava EventBus 框架的设计思想，手把手带你开发一个支持异步非阻塞的 EventBus 框架）。它可以复用在任何需要异步非阻塞观察者模式的应用场景中。 + +刚刚讲到的两个场景，不管是同步阻塞实现方式还是异步非阻塞实现方式，都是进程内的实现方式。如果用户注册成功之后，我们需要发送用户信息给大数据征信系统，而大数据征信系统是一个独立的系统，跟它之间的交互是跨不同进程的，那如何实现一个跨进程的观察者模式呢？ + +如果大数据征信系统提供了发送用户注册信息的 RPC 接口，我们仍然可以沿用之前的实现思路，在 handleRegSuccess() 函数中调用 RPC 接口来发送数据。但是，我们还有更加优雅、更加常用的一种实现方式，那就是基于消息队列（Message Queue，比如 ActiveMQ）来实现。 + +当然，这种实现方式也有弊端，那就是需要引入一个新的系统（消息队列），增加了维护成本。不过，它的好处也非常明显。在原来的实现方式中，观察者需要注册到被观察者中，被观察者需要依次遍历观察者来发送消息。而基于消息队列的实现方式，被观察者和观察者解耦更加彻底，两部分的耦合更小。被观察者完全不感知观察者，同理，观察者也完全不感知被观察者。被观察者只管发送消息到消息队列，观察者只管从消息队列中读取消息来执行相应的逻辑。 + +## EventBus 框架功能需求介 +EventBus 翻译为“事件总线”，它提供了实现观察者模式的骨架代码。我们可以基于此框架，非常容易地在自己的业务场景中实现观察者模式，不需要从零开始开发。其中，Google Guava EventBus 就是一个比较著名的 EventBus 框架，它不仅仅支持异步非阻塞模式，同时也支持同步阻塞模式 + +``` +public class UserController { + private UserService userService; // 依赖注入 + private EventBus eventBus; + private static final int DEFAULT_EVENTBUS_THREAD_POOL_SIZE = 20; + public UserController() { + //eventBus = new EventBus(); // 同步阻塞模式 + eventBus = new AsyncEventBus(Executors.newFixedThreadPool(DEFAULT_EVENTBUS_ + } + public void setRegObservers(List observers) { + for (Object observer : observers) { + eventBus.register(observer); + } + } + public Long register(String telephone, String password) { + //省略输入参数的校验代码 + //省略userService.register()异常的try-catch代码 + long userId = userService.register(telephone, password); + eventBus.post(userId); + return userId; + } +} + +public class RegPromotionObserver { + private PromotionService promotionService; // 依赖注入 + @Subscribe + public void handleRegSuccess(long userId) { + promotionService.issueNewUserExperienceCash(userId); + } +} +public class RegNotificationObserver { + private NotificationService notificationService; + @Subscribe + public void handleRegSuccess(long userId) { + notificationService.sendInboxMessage(userId, "..."); + } +} +``` +功能分析： +- register：利用 EventBus 框架实现的观察者模式，跟从零开始编写的观察者模式相比，从大的流程上来说，实现思路大致一样，都需要定义 Observer，并且通过 register() 函数注册 Observer +- post：需要通过调用某个函数（比如，EventBus 中的 post() 函数）来给 Observer 发送消息（在 EventBus 中消息被称作事件 event） + +但在实现细节方面，它们又有些区别。基于 EventBus，我们不需要定义 Observer 接口，任意类型的对象都可以注册到 EventBus 中，通过 @Subscribe 注解来标明类中哪个函数可以接收被观察者发送的消息。 + +我们详细地讲一下，Guava EventBus 的几个主要的类和函数。 +Guava EventBus 对外暴露的所有可调用接口，都封装在 EventBus 类中。其中，EventBus 实现了同步阻塞的观察者模式，AsyncEventBus 继承自 EventBus，提供了异步非阻塞的观察者模式。具体使用方式如下所示： +``` +EventBus eventBus = new EventBus(); // 同步阻塞模式 +EventBus eventBus = new AsyncEventBus(Executors.newFixedThreadPool(8)); // 异步非阻塞方式 +``` +EventBus 类提供了 register() 函数用来注册观察者。具体的函数定义如下所示。它可以接受任何类型（Object）的观察者。而在经典的观察者模式的实现中，register() 函数必须接受实现了同一 Observer 接口的类对象。 +``` +public void register(Object object); +``` +相对于 register() 函数，unregister() 函数用来从 EventBus 中删除某个观察者。 +``` +public void unregister(Object object); +``` +EventBus 类提供了 post() 函数，用来给观察者发送消息 +``` +public void post(Object event); +``` +跟经典的观察者模式的不同之处在于，当我们调用 post() 函数发送消息的时候，并非把消息发送给所有的观察者，而是发送给可匹配的观察者。所谓可匹配指的是，能接收的消息类型是发送消息（post 函数定义中的 event）类型的父类。我举个例子来解释一下。 + +比如，AObserver 能接收的消息类型是 XMsg，BObserver 能接收的消息类型是 YMsg，CObserver 能接收的消息类型是 ZMsg。其中，XMsg 是 YMsg 的父类。当我们如下发送消息的时候，相应能接收到消息的可匹配观察者如下所示： +``` +XMsg xMsg = new XMsg(); +YMsg yMsg = new YMsg(); +ZMsg zMsg = new ZMsg(); +post(xMsg); => AObserver接收到消息 +post(yMsg); => AObserver、BObserver接收到消息 +post(zMsg); => CObserver接收到消息 +``` +EventBus 最特别的一个地方，那就是 @Subscribe 注解。来标记每个 Observer 能接收消息类型的能力 +码如下所示。在 DObserver 类中，我们通过 @Subscribe 注解了两个函数 f1()、f2()。 +``` +public DObserver { + //...省略其他属性和方法... + @Subscribe + public void f1(PMsg event) { //... } + @Subscribe + public void f2(QMsg event) { //... } +} +``` +当通过 register() 函数将 DObserver 类对象注册到 EventBus 的时候，EventBus 会根据 @Subscribe 注解找到 f1() 和 f2()，并且将两个函数能接收的消息类型记录下来（PMsg->f1，QMsg->f2）。当我们通过 post() 函数发送消息（比如 QMsg 消息）的时候，EventBus 会通过之前的记录（QMsg->f2），调用相应的函数（f2）。 + +## 实现 EventBus 框架 +EventBus 中两个核心函数 register() 和 post() 的实现原理。弄懂了它们，基本上就弄懂了整个 EventBus 框架。下面两张图是这两个函数的实现原理图。 + +![](./../assets/EventBus-ObserverRegisterTable.png) +![](./../assets/EventBus-Post.png) + +最关键的一个数据结构是 Observer 注册表，记录了消息类型和可接收消息函数的对应关系。当调用 register() 函数注册观察者的时候，EventBus 通过解析 +@Subscribe 注解，生成 Observer 注册表。 + +当调用 post() 函数发送消息的时候，EventBus 通过注册表找到相应的可接收消息的函数，然后通过 Java 的反射语法来动态地创建对象、执行函数。对于同步阻塞模式，EventBus 在一个线程内依次执行相应的函数。 + +对于异步非阻塞模式，EventBus 通过一个线程池来执行相应的函数。 + +整个小框架的代码实现包括 5 个类：EventBus、AsyncEventBus、Subscribe、ObserverAction、ObserverRegistry。 + +### Subscribe +Subscribe 是一个注解，用于标明观察者中的哪个函数可以接收消息。 +``` +@Retention(RetentionPolicy.RUNTIME) +@Target(ElementType.METHOD) +@Beta +public @interface Subscribe {} +``` + +### ObserverAction +ObserverAction 类用来表示 @Subscribe 注解的方法，其中，target 表示观察者类， method 表示方法。它主要用在 ObserverRegistry 观察者注册表 +中。 +``` +public class ObserverAction { + private Object target; + private Method method; + public ObserverAction(Object target, Method method) { + this.target = Preconditions.checkNotNull(target); + this.method = method; + this.method.setAccessible(true); + } + public void execute(Object event) { // event是method方法的参数 + try { + method.invoke(target, event); + } catch (InvocationTargetException | IllegalAccessException e) { + e.printStackTrace(); + } + } +} +``` +### ObserverRegistry +ObserverRegistry 类就是前面讲到的 Observer 注册表，是最复杂的一个类，框架中几乎所有的核心逻辑都在这个类中。这个类大量使用了 Java 的反射语法，不过代码整体来说都不难理解，其中，一个比较有技巧的地方是 CopyOnWriteArraySet 的使用。 + +CopyOnWriteArraySet，顾名思义，在写入数据的时候，会创建一个新的 set，并且将原始数据 clone 到新的 set 中，在新的 set 中写入数据完成之后，再用新的 set 替换老的 set。这样就能保证在写入数据的时候，不影响数据的读取操作，以此来解决读写并发问题。除此之外，CopyOnWriteSet 还通过加锁的方式，避免了并发写冲突。具体的作用你可以去查看一下 CopyOnWriteSet 类的源码，一目了然 + +``` +作者：大志说编程 +链接：https://www.zhihu.com/question/485740418/answer/2507532102 +来源：知乎 +著作权归作者所有。商业转载请联系作者获得授权，非商业转载请注明出处。 + +public class ObserverRegistry { + /** + * key：事件类型，value：观察者包装对象 + **/ + private ConcurrentHashMap, CopyOnWriteArraySet> + registry = new ConcurrentHashMap<>(); + + /** + * 注册观察者 + * + * @param observer 观察者 + */ + public void register(Object observer) { + //获取观察者类所有的观察者方法信息 + Map, Collection> observerActions = findAllObserverActions(observer); + + for (Map.Entry, Collection> entry : observerActions.entrySet()) { + Class eventType = entry.getKey(); + + Collection eventActions = entry.getValue(); + CopyOnWriteArraySet registeredEventActions = registry.get(eventType); + + if (registeredEventActions == null) { + registry.putIfAbsent(eventType, new CopyOnWriteArraySet<>()); + registeredEventActions = registry.get(eventType); + } + //将观察者方法信息填充到map中 + registeredEventActions.addAll(eventActions); + } + } + + /** + * 获取监听器中所有的标注了@Subscribe注解的方法，并进行包装 + */ + private Map, Collection> findAllObserverActions(Object observer) { + Map, Collection> observerActions = new HashMap<>(); + + Class clazz = observer.getClass(); + + for (Method method : getAnnotatedMethods(clazz)) { + Class[] parameterTypes = method.getParameterTypes(); + //取第一个参数作为监听事件的类型 + Class eventType = parameterTypes[0]; + + if (!observerActions.containsKey(eventType)) { + observerActions.put(eventType, new ArrayList<>()); + } + observerActions.get(eventType).add(new ObserverAction(observer, method)); + } + + return observerActions; + } + + /** + * 获取标注了@Subscribe注解的方法列表 + * + * @param clazz 观察者类的class + * @return 方法列表 + */ + private List getAnnotatedMethods(Class clazz) { + List annotatedMethods = new ArrayList<>(); + + for (Method method : clazz.getDeclaredMethods()) { + if (method.isAnnotationPresent(Subscribe.class)) { + Class[] parameterTypes = method.getParameterTypes(); + Preconditions.checkArgument(parameterTypes.length == 1, + "方法 %s, 有%s个参数，@Subscribe 注解标注的方法至少含有一个参数", method, parameterTypes.length); + annotatedMethods.add(method); + } + } + return annotatedMethods; + } + + /** + * 获取匹配的监听器列表 + * + * @param event 事件类型 + * @return 监听器列表 + */ + public List getMatchObserverActions(Object event) { + List matchedObservers = new ArrayList<>(); + + Class postedEventType = event.getClass(); + + for (Map.Entry, CopyOnWriteArraySet> entry : registry.entrySet()) { + Class eventType = entry.getKey(); + Collection eventActions = entry.getValue(); + + //类是否继承自这个事件类型 + if (postedEventType.isAssignableFrom(eventType)) { + matchedObservers.addAll(eventActions); + } + } + return matchedObservers; + } + +} +``` +### EventBus +EventBus 实现的是阻塞同步的观察者模式。看代码你可能会有些疑问，这明明就用到了线程池 Executor 啊。实际上，MoreExecutors.directExecutor() 是 Google Guava 提供的工具类，看似是多线程，实际上是单线程。之所以要这么实现，主要还是为了跟 AsyncEventBus 统一代码逻辑，做到代码复用 +``` +public class EventBus { + + private ObserverRegistry registry = new ObserverRegistry(); + + private Executor executor; + + public EventBus() { + + } + + public EventBus(Executor executor) { + this.executor = executor; + } + + /** + * 注册观察者 + */ + public void register(Object observer) { + registry.register(observer); + } + + /** + * 发布者-发送消息 + */ + public void post(Object event) { + List observerActions = registry.getMatchedObserverActions(event); + for (ObserverAction observerAction : observerActions) { + if (executor == null) { + observerAction.execute(event); + } else { + executor.execute(() -> { + observerAction.execute(event); + }); + } + } + } +} +``` + +### AsyncEventBus +有了 EventBus，AsyncEventBus 的实现就非常简单了。为了实现异步非阻塞的观察者模式，它就不能再继续使用 MoreExecutors.directExecutor() 了，而是需要在构造函数中，由调用者注入线程池 +``` +public class AsyncEventBus extends EventBus { + public AsyncEventBus(Executor executor) { + super(executor); + } +} +``` diff --git a/Chapter6 - Design Pattern/6.21.md b/Chapter6 - Design Pattern/6.21.md new file mode 100644 index 0000000..88eb293 --- /dev/null +++ b/Chapter6 - Design Pattern/6.21.md @@ -0,0 +1,208 @@ +# 模板模式 + +## 定义 +模板模式，全称是模板方法设计模式，英文是 Template Method Design Pattern。在 GoF 的《设计模式》一书中，它是这么定义的： +> Define the skeleton of an algorithm in an operation, deferring some steps to subclasses. Template Method lets subclasses redefine certain steps of an algorithm without changing the algorithm’s structure. + +翻译成中文就是：模板方法模式在一个方法中定义一个算法骨架，并将某些步骤推迟到子类中实现。模板方法模式可以让子类在不改变算法整体结构的情况下，重新定义算法中的某些步骤 + +这里的“算法”，我们可以理解为广义上的“业务逻辑”，并不特指数据结构和算法中的“算法”。这里的算法骨架就是“模板”，包含算法骨架的方法就是“模板方法”，这也是模板方法模式名字的由来。 + +板模式有两大作用：复用和扩展 + +## 实现 + +原理很简单，代码实现就更加简单，我写了一个示例代码，如下所示。templateMethod() 函数定义为 final，是为了避免子类重写它。method1() 和 method2() 定义为 abstract，是为了强迫子类去实现。不过，这些都不是必须的，在实际的项目开发中，模板模式的代码实现比较灵活，待会儿讲到应用场景的时候，我们会有具体的体现。 + +``` +public abstract class AbstractClass { + public final void templateMethod() { + //... + method1(); + //... + method2(); + //... + } + protected abstract void method1(); + protected abstract void method2(); +} + +public class ConcreteClass1 extends AbstractClass { + @Override + protected void method1() { + //... + } + @Override + protected void method2() { + //... + } +} +public class ConcreteClass2 extends AbstractClass { + @Override + protected void method1() { + //... + } + @Override + protected void method2() { + //... + } +} +AbstractClass demo = ConcreteClass1(); +demo.templateMethod(); +``` + +## 应用场景 +板模式有两大作用：复用和扩展 + +### 复用 +Java InputStream +Java IO 类库中，有很多类的设计用到了模板模式，比如 InputStream、OutputStream、Reader、Writer。我们拿 InputStream 来举例说明一下。 + +把 InputStream 部分相关代码贴在了下面。在代码中，read() 函数是一个模板方法，定义了读取数据的整个流程，并且暴露了一个可以由子类来定制的抽象方法。不过这个方法也被命名为了 read()，只是参数跟模板方法不同。 +``` +public abstract class InputStream implements Closeable { + //...省略其他代码... + public int read(byte b[], int off, int len) throws IOException { + if (b == null) { + throw new NullPointerException(); + } else if (off < 0 || len < 0 || len > b.length - off) { + throw new IndexOutOfBoundsException(); + } else if (len == 0) { + return 0; + } + int c = read(); + if (c == -1) { + return -1; + } + b[off] = (byte)c; + int i = 1; + try { + for (; i < len ; i++) { + c = read(); + if (c == -1) { + break; + } + b[off + i] = (byte)c; + } + } catch (IOException ee) { + + } + return i; + } + public abstract int read() throws IOException; +} + +public class ByteArrayInputStream extends InputStream { + //...省略其他代码... + @Override + public synchronized int read() { + return (pos < count) ? (buf[pos++] & 0xff) : -1; + } +} +``` + +### 拓展 +模板模式的第二大作用的是扩展。这里所说的扩展，并不是指代码的扩展性，而是指框架的扩展性，有点类似我们之前讲到的控制反转 +基于这个作用，模板模式常用在框架的开发中，让框架用户可以在不修改框架源码的情况下，定制化框架的功能 + +JUnit 框架也通过模板模式提供了一些功能扩展点（setUp()、tearDown() 等），让框架用户可以在这些扩展点上扩展功能 + +在使用 JUnit 测试框架来编写单元测试的时候，我们编写的测试类都要继承框架提供的TestCase 类。在 TestCase 类中，runBare() 函数是模板方法，它定义了执行测试用例的整体流程：先执行 setUp() 做些准备工作，然后执行 runTest() 运行真正的测试代码，最后执行 tearDown() 做扫尾工作。 + +TestCase 类的具体代码如下所示。尽管 setUp()、tearDown() 并不是抽象函数，还提供了默认的实现，不强制子类去重新实现，但这部分也是可以在子类中定制的，所以也符合模板模式的定义。 + +``` +public abstract class TestCase extends Assert implements Test { + public void runBare() throws Throwable { + Throwable exception = null; + setUp(); + try { + runTest(); + } catch (Throwable running) { + exception = running; + } finally { + try { + tearDown(); + } catch (Throwable tearingDown) { + if (exception == null) exception = tearingDown; + } + } + if (exception != null) throw exception; + } + /** + * Sets up the fixture, for example, open a network connection. + * This method is called before a test is executed. + */ + protected void setUp() throws Exception { + } + + /** + * Tears down the fixture, for example, close a network connection. + * This method is called after a test is executed. + */ + protected void tearDown() throws Exception { + } +} +``` + +在 iOS 2.0 开始，App 可以通过重载 UIView 类中的`-(void)drawRect:(CGRect)rect;` 方法来执行定制绘图 +这个方法的默认实现什么也不做，UIView 的子类如果需要真的自己绘制视图，就可以重载这个方法，这个方法也是钩子方法 +当需要改变屏幕上的视图时，这个方法会被调用，框架会处理所有底层的苦差事，以实现这一点。由 UIView 处理绘图过程的部分会调用 drawRect。如果这个方法内有代码，那么会被调用。 + + +## 思考：模板模式与Callback回调函数有何区别和联系 +复用和扩展是模板模式的两大作用，实际上，还有另外一个技术概念，也能起到跟模板模式相同的作用，那就是回调（Callback）。今天我们今天就来看一下，回调的原理、实现和应用，以及它跟模板模式的区别和联系 + +### 回调的原理解析 +相对于普通的函数调用来说，回调是一种双向调用关系。A 类事先注册某个函数 F 到 B 类，A 类在调用 B 类的 P 函数的时候，B 类反过来调用 A 类注册给它的 F 函数。这里的 F 函数就是“回调函数”。A 调用 B，B 反过来又调用 A，这种调用机制就叫作“回调”。 + +A 类如何将回调函数传递给 B 类呢？不同的编程语言，有不同的实现方法。C 语言可以使用函数指针，Java 则需要使用包裹了回调函数的类对象，我们简称为回调对象。这里用Java 语言举例说明一下。代码如下所示： +``` +public interface ICallback { + void methodToCallback(); +} +public class BClass { + public void process(ICallback callback) { + //... + callback.methodToCallback(); + //... + } +} +public class AClass { + public static void main(String[] args) { + BClass b = new BClass(); + b.process(new ICallback() { //回调对象 + @Override + public void methodToCallback() { + System.out.println("Call back me."); + } + }); + } +} +``` +上面就是 Java 语言中回调的典型代码实现。从代码实现中，我们可以看出，回调跟模板模式一样，也具有复用和扩展的功能。除了回调函数之外，BClass 类的 process() 函数中的逻辑都可以复用。如果 ICallback、BClass 类是框架代码，AClass 是使用框架的客户端代码，我们可以通过 ICallback 定制 process() 函数，也就是说，框架因此具有了扩展的能力 + +实际上，回调不仅可以应用在代码设计上，在更高层次的架构设计上也比较常用。比如，通过三方支付系统来实现支付功能，用户在发起支付请求之后，一般不会一直阻塞到支付结果返回，而是注册回调接口（类似回调函数，一般是一个回调用的 URL）给三方支付系统，等三方支付系统执行完成之后，将结果通过回调接口返回给用户。 + +回调可以分为同步回调和异步回调（或者延迟回调）。同步回调指在函数返回之前执行回调函数；异步回调指的是在函数返回之后执行回调函数。上面的代码实际上是同步回调的实现方式，在 process() 函数返回之前，执行完回调函数 methodToCallback()。而上面支付的例子是异步回调的实现方式，发起支付之后不需要等待回调接口被调用就直接返回。从应用场景上来看，同步回调看起来更像模板模式，异步回调看起来更像观察者模式 + +实际场景的例子 +在客户端开发中，我们经常给控件注册事件监听器，比如下面这段代码，就是在 Android 应用开发中，给 Button 控件的点击事件注册监听器。 +``` +Button button = (Button)findViewById(R.id.button); +button.setOnClickListener(new OnClickListener() { + @Override + public void onClick(View v) { + System.out.println("I am clicked."); + } +}); +``` +从代码结构上来看，事件监听器很像回调，即传递一个包含回调函数（onClick()）的对象给另一个函数。从应用场景上来看，它又很像观察者模式，即事先注册观察者（OnClickListener），当用户点击按钮的时候，发送点击事件给观察者，并且执行相应的 onClick() 函数。 + +我们前面讲到，回调分为同步回调和异步回调。这里的回调算是异步回调，我们往 setOnClickListener() 函数中注册好回调函数之后，并不需要等待回调函数执行。这也印证了我们前面讲的，异步回调比较像观察者模式 + +## 总结 +模板方法模式在一个方法中定义一个算法骨架，并将某些步骤推迟到子类中实现。模板方法模式可以让子类在不改变算法整体结构的情况下，重新定义算法中的某些步骤。这里的“算法”，我们可以理解为广义上的“业务逻辑”，并不特指数据结构和算法中的“算法”。这里的算法骨架就是“模板”，包含算法骨架的方法就是“模板方法”，这也是模板方法模式名字的由来 + +模板模式有两大作用：复用和扩展。其中，复用指的是，所有的子类可以复用父类中提供的模板方法的代码。扩展指的是，框架通过模板模式提供功能扩展点，让框架用户可以在不修改框架源码的情况下，基于扩展点定制化框架的功能 + diff --git a/Chapter6 - Design Pattern/6.22.md b/Chapter6 - Design Pattern/6.22.md new file mode 100644 index 0000000..4f798df --- /dev/null +++ b/Chapter6 - Design Pattern/6.22.md @@ -0,0 +1,384 @@ +# 策略模式 +> 如何避免冗长的if-else-switch分支判断代码 + +## 定义 +策略模式，英文全称是 Strategy Design Pattern。在 GoF 的《设计模式》一书中，它是这样定义的： +> Define a family of algorithms, encapsulate each one, and make them interchangeable. Strategy lets the algorithm vary independently from clients that use it. +翻译成中文就是：定义一族算法类，将每个算法分别封装起来，让它们可以互相替换。策略模式可以使算法的变化独立于使用它们的客户端（这里的客户端代指使用算法的代码）。 + +**工厂模式是解耦对象的创建和使用，观察者模式是解耦观察者和被观察者。策略模式跟两者类似，也能起到解耦的作用，不过，它解耦的是策略的定义、创建、使用**。 + +## 策略的定义 +策略类的定义比较简单，包含一个策略接口和一组实现这个接口的策略类。因为所有的策略类都实现相同的接口，所以，客户端代码基于接口而非实现编程，可以灵活地替换不同的策略。示例代码如下所示： + +``` +public interface Strategy { + void algorithmInterface(); +} +public class ConcreteStrategyA implements Strategy { + @Override + public void algorithmInterface() { + //具体的算法... + } +} +public class ConcreteStrategyB implements Strategy { + @Override + public void algorithmInterface() { + // 具体的算法... + } +} +``` +## 策略的创建 +因为策略模式会包含一组策略，在使用的时候，一般会通过类型（type）来判断创建哪个策略来使用，为了封装创建逻辑，我们需要对客户端代码屏蔽创建细节，所以可以把 type 创建策略部分的逻辑抽取出来，放到工厂类中 +``` +public class StrategyFactory { + private static final Map strategies = new HashMap<>(); + static { + strategies.put("A", new ConcreteStrategyA()); + strategies.put("B", new ConcreteStrategyB()); + } + public static Strategy getStrategy(String type) { + if (type == null || type.isEmpty()) { + throw new IllegalArgumentException("type should not be empty."); + } + return strategies.get(type); + } +} +``` +一般来讲，如果策略类是无状态的，不包含成员变量，只是纯粹的算法实现，这样的策略对象是可以被共享使用的，不需要在每次调用 getStrategy() 的时候，都创建一个新的策略对象。针对这种情况，我们可以使用上面这种工厂类的实现方式，事先创建好每个策略对象，缓存到工厂类中，用的时候直接返回 + +相反，如果策略类是有状态的，根据业务场景的需要，我们希望每次从工厂方法中，获得的都是新创建的策略对象，而不是缓存好可共享的策略对象，那我们就需要按照 +如下方式来实现策略工厂类。 + +``` +public class StrategyFactory { + public static Strategy getStrategy(String type) { + if (type == null || type.isEmpty()) { + throw new IllegalArgumentException("type should not be empty."); + } + if (type.equals("A")) { + return new ConcreteStrategyA(); + } else if (type.equals("B")) { + return new ConcreteStrategyB(); + } + return null; + } +} +``` + +## 策略的使用 +我们知道，策略模式包含一组可选策略，客户端代码一般如何确定使用哪个策略呢？最常见的是运行时动态确定使用哪种策略，这也是策略模式最典型的应用场景。 +这里的“运行时动态”指的是，我们事先并不知道会使用哪个策略，而是在程序运行期间，根据配置、用户输入、计算结果等这些不确定因素，动态决定使用哪种策略。接下来，我们通过一个例子来解释一下 +``` +// 策略接口：EvictionStrategy +// 策略类：LruEvictionStrategy、FifoEvictionStrategy、LfuEvictionStrategy... +// 策略工厂：EvictionStrategyFactory +public class UserCache { + private Map cacheData = new HashMap<>(); + private EvictionStrategy eviction; + public UserCache(EvictionStrategy eviction) { + this.eviction = eviction; + } + //... +} +// 运行时动态确定，根据配置文件的配置决定使用哪种策略 +public class Application { + public static void main(String[] args) throws Exception { + Properties props = new Properties(); + props.load(new FileInputStream("./config.properties")); + String type = props.getProperty("eviction_type"); + evictionStrategy = EvictionStrategyFactory.getEvictionStrategy(type); + UserCache userCache = new UserCache(evictionStrategy); + //... + } +} +// 非运行时动态确定，在代码中指定使用哪种策略 +public class Application { + public static void main(String[] args) { + //... + EvictionStrategy evictionStrategy = new LruEvictionStrategy(); + UserCache userCache = new UserCache(evictionStrategy); + //... + } +} +``` +从上面的代码中，我们也可以看出，“非运行时动态确定”，也就是第二个 Application 中的使用方式，并不能发挥策略模式的优势。在这种应用场景下，策略模式实际上退化成了“面向对象的多态特性”或“基于接口而非实现编程原则”。 + +## 如何利用策略模式避免分支判断？ +实际上，能够移除分支判断逻辑的模式不仅仅有策略模式，后面我们要讲的状态模式也可以。对于使用哪种模式，具体还要看应用场景来定。 策略模式适用于根据不同类型待动态，决定使用哪种策略这样一种应用场景。 + +我们先通过一个例子来看下，if-else 或 switch-case 分支判断逻辑是如何产生的。具体的 代码如下所示。在这个例子中，我们没有使用策略模式，而是将策略的定义、创建、使用直接耦合在一起。 +``` +public class OrderService { + public double discount(Order order) { + double discount = 0.0; + OrderType type = order.getType(); + if (type.equals(OrderType.NORMAL)) { // 普通订单 + //...省略折扣计算算法代码 + } else if (type.equals(OrderType.GROUPON)) { // 团购订单 + //...省略折扣计算算法代码 + } else if (type.equals(OrderType.PROMOTION)) { // 促销订单 + //...省略折扣计算算法代码 + } + return discount; + } +} +``` +如何来移除掉分支判断逻辑呢？那策略模式就派上用场了。我们使用策略模式对上面的代码重构，将不同类型订单的打折策略设计成策略类，并由工厂类来负责创建策略对象。具体的代码如下所示 +``` +/ 策略的定义 +public interface DiscountStrategy { + double calDiscount(Order order); +} +// 省略 NormalDiscountStrategy、GrouponDiscountStrategy、PromotionDiscountStrateg + + +// 策略的创建 +public class DiscountStrategyFactory { + private static final Map strategies = new HashMa + static { + strategies.put(OrderType.NORMAL, new NormalDiscountStrategy()); + strategies.put(OrderType.GROUPON, new GrouponDiscountStrategy()); + strategies.put(OrderType.PROMOTION, new PromotionDiscountStrategy()); + } + public static DiscountStrategy getDiscountStrategy(OrderType type) { + return strategies.get(type); + } +} + +// 策略的使用 +public class OrderService { + public double discount(Order order) { + OrderType type = order.getType(); + DiscountStrategy discountStrategy = DiscountStrategyFactory.getDiscountStra + return discountStrategy.calDiscount(order); + } +} +``` +重构之后的代码就没有了 if-else 分支判断语句了。实际上，这得益于策略工厂类。在工厂类中，我们用 Map 来缓存策略，根据 type 直接从 Map 中获取对应的策略，从而避免 if-else 分支判断逻辑。等后面讲到使用状态模式来避免分支判断逻辑的时候，你会发现，它们使用的是同样的套路。本质上都是借助“查表法”，根据 type 查表（代码中的 strategies 就是表）替代根据 type 分支判断。 + +但是，如果业务场景需要每次都创建不同的策略对象，我们就要用另外一种工厂类的实现方式了 +``` +public class DiscountStrategyFactory { + public static DiscountStrategy getDiscountStrategy(OrderType type) { + if (type == null) { + throw new IllegalArgumentException("Type should not be null."); + } + if (type.equals(OrderType.NORMAL)) { + return new NormalDiscountStrategy(); + } else if (type.equals(OrderType.GROUPON)) { + return new GrouponDiscountStrategy(); + } else if (type.equals(OrderType.PROMOTION)) { + return new PromotionDiscountStrategy(); + } + return null; + } +} +``` +这种实现方式相当于把原来的 if-else 分支逻辑，从 OrderService 类中转移到了工厂类中，实际上并没有真正将它移除 + +## 一个实际场景：如何实现一个支持给不同大小文件排序的小程序 +设计原则和思想其实比设计模式更加普适和重要，掌握了代码的设计原则和思想，我们甚至可以自己创造出来新的设计模式 + +假设有这样一个需求，希望写一个小程序，实现对一个文件进行排序的功能。文件中只包含整型数，并且，相邻的数字通过逗号来区隔。如果由你来编写这样一个小程序，你会如何来实现呢？ + +### 问题与解决思路 +这不是很简单嘛，只需要将文件中的内容读取出来，并且通过逗号分割成一个一个的数字，放到内存数组中，然后编写某种排序算法（比如快排），或者直接使用编程语言提供的排序函数，对数组进行排序，最后再将数组中的数据写入文件就可以了。 + +但是，如果文件很大呢？比如有 10GB 大小，因为内存有限（比如只有 8GB 大小），我们没办法一次性加载文件中的所有数据到内存中，这个时候，我们就要利用外部排序算法了。 + +如果文件更大，比如有 100GB 大小，我们为了利用 CPU 多核的优势，可以在外部排序的基础之上进行优化，加入多线程并发排序的功能，这就有点类似“单机版”的 MapReduce。 + +如果文件非常大，比如有 1TB 大小，即便是单机多线程排序，这也算很慢了。这个时候，我们可以使用真正的 MapReduce 框架，利用多机的处理能力，提高排序效率 + +### 代码实现与分析 +简易版本 +``` +public class Sorter { + private static final long GB = 1000 * 1000 * 1000; + public void sortFile(String filePath) { + // 省略校验逻辑 + File file = new File(filePath); + long fileSize = file.length(); + if (fileSize < 6 * GB) { // [0, 6GB) + quickSort(filePath); + } else if (fileSize < 10 * GB) { // [6GB, 10GB) + externalSort(filePath); + } else if (fileSize < 100 * GB) { // [10GB, 100GB) + concurrentExternalSort(filePath); + } else { // [100GB, ~) + mapreduceSort(filePath); + } + } + private void quickSort(String filePath) { + // 快速排序 + } + private void externalSort(String filePath) { + // 外部排序 + } + private void concurrentExternalSort(String filePath) { + // 多线程外部排序 + } + private void mapreduceSort(String filePath) { + // 利用MapReduce多机排序 + } +} +public class SortingTool { + public static void main(String[] args) { + Sorter sorter = new Sorter(); + sorter.sortFile(args[0]); + } +} +``` +问题分析： +在“编码规范”那一部分我们讲过，函数的行数不能过多，最好不要超过一屏的大小。所以，为了避免 sortFile() 函数过长，我们把每种排序算法从 sortFile() 函数中抽离出来，拆分成 4 个独立的排序函数。 + +如果只是开发一个简单的工具，那上面的代码实现就足够了。毕竟，代码不多，后续修改、扩展的需求也不多，怎么写都不会导致代码不可维护。但是，如果我们是在开发一个大型项目，排序文件只是其中的一个功能模块，那我们就要在代码设计、代码质量上下点儿功夫了。只有每个小的功能模块都写好，整个项目的代码才能不差。 + +### 代码优化与重构 +设计原则和思想，针对上面的问题，即便我们想不到该用什么设计模式来重构，也应该能知道该如何解决，那就是将 Sorter 类中的某些代码拆分出来，独立成职责更加单一的小类。实际上，拆分是应对类或者函数代码过多、应对代码复杂性的一个常用手段。按照这个解决思路，我们对代码进行重构。 +``` +public interface ISortAlg { + void sort(String filePath); +} +public class QuickSort implements ISortAlg { + @Override + public void sort(String filePath) { + //... + } +} +public class ExternalSort implements ISortAlg { + @Override + public void sort(String filePath) { + //... + } +} +public class ConcurrentExternalSort implements ISortAlg { + @Override + public void sort(String filePath) { + //... + } +} +public class MapReduceSort implements ISortAlg { + @Override + public void sort(String filePath) { + //... + } +} + +public class Sorter { + private static final long GB = 1000 * 1000 * 1000; + public void sortFile(String filePath) { + // 省略校验逻辑 + File file = new File(filePath); + long fileSize = file.length(); + ISortAlg sortAlg; + if (fileSize < 6 * GB) { // [0, 6GB) + sortAlg = new QuickSort(); + } else if (fileSize < 10 * GB) { // [6GB, 10GB) + sortAlg = new ExternalSort(); + } else if (fileSize < 100 * GB) { // [10GB, 100GB) + sortAlg = new ConcurrentExternalSort(); + } else { // [100GB, ~) + sortAlg = new MapReduceSort(); + } + sortAlg.sort(filePath); + } +} +``` +问题分析： +经过拆分之后，每个类的代码都不会太多，每个类的逻辑都不会太复杂，代码的可读性、可维护性提高了。除此之外，我们将排序算法设计成独立的类，跟具体的业务逻辑（代码中的 if-else 那部分逻辑）解耦，也让排序算法能够复用。这一步实际上就是策略模式的第一步，也就是将策略的定义分离出来。 + +实际上，上面的代码还可以继续优化。每种排序类都是无状态的，我们没必要在每次使用的时候，都重新创建一个新的对象。所以，我们可以使用工厂模式对对象的创建进行封装。按照这个思路，我们对代码进行重构。重构之后的代码如下所示 +``` +public class SortAlgFactory { + private static final Map algs = new HashMap<>(); + static { + algs.put("QuickSort", new QuickSort()); + algs.put("ExternalSort", new ExternalSort()); + algs.put("ConcurrentExternalSort", new ConcurrentExternalSort()); + algs.put("MapReduceSort", new MapReduceSort()); + } + public static ISortAlg getSortAlg(String type) { + if (type == null || type.isEmpty()) { + throw new IllegalArgumentException("type should not be empty."); + } + return algs.get(type); + } +} +public class Sorter { + private static final long GB = 1000 * 1000 * 1000; + public void sortFile(String filePath) { + // 省略校验逻辑 + File file = new File(filePath); + long fileSize = file.length(); + ISortAlg sortAlg; + if (fileSize < 6 * GB) { // [0, 6GB) + sortAlg = SortAlgFactory.getSortAlg("QuickSort"); + } else if (fileSize < 10 * GB) { // [6GB, 10GB) + sortAlg = SortAlgFactory.getSortAlg("ExternalSort"); + } else if (fileSize < 100 * GB) { // [10GB, 100GB) + sortAlg = SortAlgFactory.getSortAlg("ConcurrentExternalSort"); + } else { // [100GB, ~) + sortAlg = SortAlgFactory.getSortAlg("MapReduceSort"); + } + sortAlg.sort(filePath); + } +} +``` +问题分析： +经过上面两次重构之后，现在的代码实际上已经符合策略模式的代码结构了。我们通过策略模式将策略的定义、创建、使用解耦，让每一部分都不至于太复杂。不过，Sorter 类中的 sortFile() 函数还是有一堆 if-else 逻辑。这里的 if-else 逻辑分支不多、也不复杂，这样写完全没问题。但如果你特别想将 if-else 分支判断移除掉，那也是有办法的。我直接给出代码，你一看就能明白。实际上，这也是基于查表法来解决的，其中的“algs”就是“表”。 +``` +public class Sorter { + private static final long GB = 1000 * 1000 * 1000; + private static final List algs = new ArrayList<>(); + static { + algs.add(new AlgRange(0, 6*GB, SortAlgFactory.getSortAlg("QuickSort"))); + algs.add(new AlgRange(6*GB, 10*GB, SortAlgFactory.getSortAlg("ExternalSort + algs.add(new AlgRange(10*GB, 100*GB, SortAlgFactory.getSortAlg("ConcurrentE + algs.add(new AlgRange(100*GB, Long.MAX_VALUE, SortAlgFactory.getSortAlg("Ma + } + public void sortFile(String filePath) { + // 省略校验逻辑 + File file = new File(filePath); + long fileSize = file.length(); + ISortAlg sortAlg = null; + for (AlgRange algRange : algs) { + if (algRange.inRange(fileSize)) { + sortAlg = algRange.getAlg(); + break; + } + } + sortAlg.sort(filePath); + } + + private static class AlgRange { + private long start; + private long end; + private ISortAlg alg; + public AlgRange(long start, long end, ISortAlg alg) { + this.start = start; + this.end = end; + this.alg = alg; + } + public ISortAlg getAlg() { + return alg; + } + public boolean inRange(long size) { + return size >= start && size < end; + } + } +} +``` + +## 总结 +一提到 if-else 分支判断，有人就觉得它是烂代码。如果 if-else 分支判断不复杂、代码不多，这并没有任何问题，毕竟 if-else 分支判断几乎是所有编程语言都会提供的语法，存在即有理由。遵循 KISS 原则，怎么简单怎么来，就是最好的设计。非得用策略模式，搞出 n 多类，反倒是一种过度设计。 + +一提到策略模式，有人就觉得，它的作用是避免 if-else 分支判断逻辑。实际上，这种认识是很片面的。策略模式主要的作用还是解耦策略的定义、创建和使用，控制代码的复杂度，让每个部分都不至于过于复杂、代码量过多。除此之外，对于复杂代码来说，策略模式还能让其满足开闭原则，添加新策略的时候，最小化、集中化代码改动，减少引入 bug 的风险。 + +策略模式定义一族算法类，将每个算法分别封装起来，让它们可以互相替换。策略模式可以使算法的变化独立于使用它们的客户端（这里的客户端代指使用算法的代码） +策略模式用来解耦策略的定义、创建、使用。实际上，一个完整的策略模式就是由这三个部分组成的。 +- 策略类的定义比较简单，包含一个策略接口和一组实现这个接口的策略类 +- 策略的创建由工厂类来完成，封装策略创建的细节。 +- 策略模式包含一组策略可选，客户端代码如何选择使用哪个策略，有两种确定方法：编译时静态确定和运行时动态确定。其中，“运行时动态确定”才是策略模式最典型的应用场景。 +除此之外，我们还可以通过策略模式来移除 if-else 分支判断。实际上，这得益于策略工厂类，更本质上点讲，是借助“查表法”，根据 type 查表替代根据 type 分支判断。 \ No newline at end of file diff --git a/Chapter6 - Design Pattern/6.23.md b/Chapter6 - Design Pattern/6.23.md new file mode 100644 index 0000000..d457044 --- /dev/null +++ b/Chapter6 - Design Pattern/6.23.md @@ -0,0 +1,171 @@ +# 职责链模式 + +## 定义 +职责链模式的英文翻译是 Chain Of Responsibility Design Pattern。在 GoF 的《设计模式》中，它是这么定义的： +> Avoid coupling the sender of a request to its receiver by giving more than one object a chance to handle the request. Chain the receiving objects and pass the request along the chain until an object handles it. + +翻译成中文就是：将请求的发送和接收解耦，让多个接收对象都有机会处理这个请求。将这些接收对象串成一条链，并沿着这条链传递这个请求，直到链上的某个接收对象能够处理它为止 + +在职责链模式中，多个处理器（也就是刚刚定义中说的“接收对象”）依次处理同一个请求。一个请求先经过 A 处理器处理，然后再把请求传递给 B 处理器，B 处理器处理完后再传递给 C 处理器，以此类推，形成一个链条。链条上的每个处理器各自承担各自的处理职责，所以叫作职责链模式。 + +有些抽象，可以类比下 Node 的洋葱模型，是不是形象多了 + + +## 实现 + +### 方法1 +Handler 是所有处理器类的抽象父类，handle() 是抽象方法。每个具体的处理器类（HandlerA、HandlerB）的 handle() 函数的代码结构类似，如果它能处理该请求，就不继续往下传递；如果不能处理，则交由后面的处理器来处理（也就是调用 successor.handle()）。 +HandlerChain 是处理器链，从数据结构的角度来看，它就是一个记录了链头、链尾的链表。其中，记录链尾是为了方便添加处理器。 + +``` +public abstract class Handler { + protected Handler successor = null; + public void setSuccessor(Handler successor) { + this.successor = successor; + } + public abstract void handle(); +} +public class HandlerA extends Handler { + @Override + public boolean handle() { + boolean handled = false; + //... + if (!handled && successor != null) { + successor.handle(); + } + } +} + +public class HandlerB extends Handler { + @Override + public void handle() { + boolean handled = false; + //... + if (!handled && successor != null) { + successor.handle(); + } + } +} +public class HandlerChain { + private Handler head = null; + private Handler tail = null; + public void addHandler(Handler handler) { + handler.setSuccessor(null); + if (head == null) { + head = handler; + tail = handler; + return; + } + tail.setSuccessor(handler); + tail = handler; + } + public void handle() { + if (head != null) { + head.handle(); + } + } +} + +// 使用举例 +public class Application { + public static void main(String[] args) { + HandlerChain chain = new HandlerChain(); + chain.addHandler(new HandlerA()); + chain.addHandler(new HandlerB()); + chain.handle(); + } +} +``` + +问题分析：上面的代码实现不够优雅。处理器类的 handle() 函数，不仅包含自己的业务逻辑，还包含对下一个处理器的调用，也就是代码中的 successor.handle()。一个不熟悉这种代码结构的程序员，在添加新的处理器类的时候，很有可能忘记在 handle() 函数中调用 successor.handle()，这就会导致代码出现 bug + +我们对代码进行重构，**利用模板模式，将调用 successor.handle() 的逻辑从具体的处理器类中剥离出来，放到抽象父类中**。这样具体的处理器类只需要实现自己的业务逻辑就可以了。重构之后的代码如下所示 + +``` +public abstract class Handler { + protected Handler successor = null; + public void setSuccessor(Handler successor) { + this.successor = successor; + } + public final void handle() { + boolean handled = doHandle(); + if (successor != null && !handled) { + successor.handle(); + } + } + protected abstract boolean doHandle(); + } + public class HandlerA extends Handler { + @Override + protected boolean doHandle() { + boolean handled = false; + //... + return handled; + } +} + +public class HandlerB extends Handler { + @Override + protected boolean doHandle() { + boolean handled = false; + //... + return handled; + } +} +// HandlerChain和Application代码不变 +``` +### 方法2 +我们再来看第二种实现方式，代码如下所示。这种实现方式更加简单。HandlerChain 类用数组而非链表来保存所有的处理器，并且需要在 HandlerChain 的 handle() 函数中，依次调用每个处理器的 handle() 函数。 + +``` +public interface IHandler { + boolean handle(); +} +public class HandlerA implements IHandler { + @Override + public boolean handle() { + boolean handled = false; + //... + return handled; + } +} +public class HandlerB implements IHandler { + @Override + public boolean handle() { + boolean handled = false; + //... + return handled; + } +} +public class HandlerChain { + private List handlers = new ArrayList<>(); + public void addHandler(IHandler handler) { + this.handlers.add(handler); + } + public void handle() { + for (IHandler handler : handlers) { + + boolean handled = handler.handle(); + if (handled) { + break; + } + } + } +} + +// 使用举例 +public class Application { + public static void main(String[] args) { + HandlerChain chain = new HandlerChain(); + chain.addHandler(new HandlerA()); + chain.addHandler(new HandlerB()); + chain.handle(); + } +} +``` +在 GoF 给出的定义中，如果处理器链上的某个处理器能够处理这个请求，那就不会继续往下传递请求。实际上，职责链模式还有一种变体，那就是请求会被所有的处理器都处理一遍，不存在中途终止的情况。 + +## 使用场景 +在之前的文章利用[责任链模式设计了一套校验器](./../Chapter1%20-%20iOS/1.110.md) +再举个例子敏感词过滤的例子。 + diff --git a/Chapter6 - Design Pattern/6.3.md b/Chapter6 - Design Pattern/6.3.md new file mode 100644 index 0000000..aac1359 --- /dev/null +++ b/Chapter6 - Design Pattern/6.3.md @@ -0,0 +1,106 @@ +# SOLID之单一职责 SRP + +单一职责原则的英文是 Single Responsibility Principle，缩写为 SRP。这个原则的英文描 +述是这样的：A class or module should have a single reponsibility。如果我们把它翻译 +成中文，那就是：一个类或者模块只负责完成一个职责（或者功能）。 + + +一个类里既包含订单的一些操作，又包含用户的一些操作。而订单和用户是两个独立的业务领域模型，我们将两个不相干的功能放到同一个类中，那就违反了单一职责原则。为了满足单一职责原则，我们需要将这个类拆分成两个粒度更细、功能更加单一的两个类：订单类和用户类。 + +## 如何判断类的职责是否足够单一？ +在一个社交产品中，我们用下面的 UserInfo 类来记录用户的信息。你觉得，UserInfo 类的 +设计是否满足单一职责原则呢？ + +``` +public class UserInfo { + private long userId; + private String username; + private String email; + private String telephone; + private long createTime; + private long lastLoginTime; + private String avatarUrl; + private String provinceOfAddress; // 省 + private String cityOfAddress; // 市 + private String regionOfAddress; // 区 + private String detailedAddress; // 详细地址 + // ... 省略其他属性和方法... +} +``` +对于这个问题，有两种不同的观点。一种观点是，UserInfo 类包含的都是跟用户相关的信息，所有的属性和方法都隶属于用户这样一个业务模型，满足单一职责原则；另一种观点是，地址信息在 UserInfo 类中，所占的比重比较高，可以继续拆分成独立的 UserAddress 类，UserInfo 只保留除 Address 之外的其他信息，拆分之后的两个类的职责更加单一。 + +哪种观点更对呢？实际上，要从中做出选择，我们不能脱离具体的应用场景。如果在这个社交产品中，用户的地址信息跟其他信息一样，只是单纯地用来展示，那 UserInfo 现在的设计就是合理的。但是，如果这个社交产品发展得比较好，之后又在产品中添加了电商的模块，用户的地址信息还会用在电商物流中，那我们最好将地址信息从 UserInfo 中拆分出来，独立成用户物流信息（或者叫地址信息、收货信息等）。 + +我们再进一步延伸一下。如果做这个社交产品的公司发展得越来越好，公司内部又开发出了跟多其他产品（可以理解为其他 App）。公司希望支持统一账号系统，也就是用户一个账号可以在公司内部的所有产品中登录。这个时候，我们就需要继续对 UserInfo 进行拆分，将跟身份认证相关的信息（比如，email、telephone 等）抽取成独立的类。 + +从刚刚这个例子，我们可以总结出，不同的应用场景、不同阶段的需求背景下，对同一个类的职责是否单一的判定，可能都是不一样的。在某种应用场景或者当下的需求背景下，一个类的设计可能已经满足单一职责原则了，但如果换个应用场景或着在未来的某个需求背景下，可能就不满足了，需要继续拆分成粒度更细的类。 + + +评价一个类的职责是否足够单一，我们并没有一个非常明确的、可以量化的标准，可以说，这是件非常主观、仁者见仁智者见智的事情。实际上，在真正的软件开发中， +我们也没必要过于未雨绸缪，过度设计。所以，我们可以先写一个粗粒度的类，满足业务需求。随着业务的发展，如果粗粒度的类越来越庞大，代码越来越多，这个时候，我们就可以将这个粗粒度的类，拆分成几个更细粒度的类。这就是所谓的持续重构。 + + +## 类的职责是否设计得越单一越好？ +为了满足单一职责原则，是不是把类拆得越细就越好呢？答案是否定的。我们还是通过一个例子来解释一下。Serialization 类实现了一个简单协议的序列化和反序列功能，具体代码如下： +``` +/** +* Protocol format: identifier-string;{gson string} +* For example: UEUEUE;{"a":"A","b":"B"} +*/ +public class Serialization { + private static final String IDENTIFIER_STRING = "UEUEUE;"; + private Gson gson; + public Serialization() { + public class Serialization { + this.gson = new Gson(); + } + public String serialize(Map object) { + StringBuilder textBuilder = new StringBuilder(); + textBuilder.append(IDENTIFIER_STRING); + textBuilder.append(gson.toJson(object)); + return textBuilder.toString(); + } + public Map deserialize(String text) { + if (!text.startsWith(IDENTIFIER_STRING)) { + return Collections.emptyMap(); + } + String gsonStr = text.substring(IDENTIFIER_STRING.length()); + return gson.fromJson(gsonStr, Map.class); + } +} +``` +如果我们想让类的职责更加单一，我们对 Serialization 类进一步拆分，拆分成一个只负责序列化工作的 Serializer 类和另一个只负责反序列化工作的 Deserializer 类。拆分后的具体代码如下所示： +``` +public class Serializer { + private static final String IDENTIFIER_STRING = "UEUEUE;"; + private Gson gson; + public Serializer() { + this.gson = new Gson(); + } + public String serialize(Map object) { + StringBuilder textBuilder = new StringBuilder(); + textBuilder.append(IDENTIFIER_STRING); + textBuilder.append(gson.toJson(object)); + return textBuilder.toString(); + } +} + +public class Deserializer { + private static final String IDENTIFIER_STRING = "UEUEUE;"; + private Gson gson; + public Deserializer() { + this.gson = new Gson(); + } + + public Map deserialize(String text) { + if (!text.startsWith(IDENTIFIER_STRING)) { + return Collections.emptyMap(); + } + String gsonStr = text.substring(IDENTIFIER_STRING.length()); + return gson.fromJson(gsonStr, Map.class); + } +} +``` +虽然经过拆分之后，Serializer 类和 Deserializer 类的职责更加单一了，但也随之带来了新的问题。如果我们修改了协议的格式，数据标识从“UEUEUE”改为“DFDFDF”，或者序列化方式从 JSON 改为了 XML，那 Serializer 类和 Deserializer 类都需要做相应的修改，代码的内聚性显然没有原来 Serialization 高了。而且，如果我们仅仅对 Serializer 类做了协议修改，而忘记了修改 Deserializer 类的代码，那就会导致序列化、反序列化不匹配，程序运行出错，也就是说，拆分之后，代码的可维护性变差了。实际上，不管是应用设计原则还是设计模式，最终的目的还是提高代码的可读性、可扩展性、复用性、可维护性等。我们在考虑应用某一个设计原则是否合理的时候，也可以以此作为最终的考量标准。 + + diff --git a/Chapter6 - Design Pattern/6.4.md b/Chapter6 - Design Pattern/6.4.md new file mode 100644 index 0000000..8a68d60 --- /dev/null +++ b/Chapter6 - Design Pattern/6.4.md @@ -0,0 +1,224 @@ +# SOLID之开闭原则 + +如何做到“对扩展开放、修改关闭”？扩展和修改各指什么？ + + +## 如何理解“对扩展开放、修改关闭”？ +开闭原则的英文全称是 Open Closed Principle，简写为 OCP。它的英文描述是：Software entities (modules, classes, functions, etc.) should be open for extension , +but closed for modification。 + +解释一下就是：添加一个新的功能应该是，在已有代码基础上扩展代码（新增模块、类、方法等），而非修改已有代码（修改模块、类、方法等）。 + +举个场景例子，之前在做天网报警系统的时候，有一段监控告警代码。 + +其中 AlertRule 存储告警规则，有个 mPaaS 平台的可视化页面，基于不同业务线自由设置。Notification 是告警通知类，支持邮件、短信、微信、手机等多种通知渠道。NotificationEmergencyLevel 表示通知的紧急程度：Error、Warning、Info、Normal。 + +``` +public class Alert { + private AlertRule rule; + private Notification notification; + + public Alert(AlertRule rule, Notification notification) { + this.rule = rule; + this.notification = notification; + } + public void check(String api, long requestCount, long errorCount, long durationOfSeconds) { + long tps = requestCount / durationOfSeconds; + if (tps > rule.getMatchedRule(api).getMaxTps()) { + notification.notify(NotificationEmergencyLevel.URGENCY, "..."); + } + if (errorCount > rule.getMatchedRule(api).getMaxErrorCount()) { + notification.notify(NotificationEmergencyLevel.SEVERE, "..."); + } + } +} +``` +上面这段代码非常简单，业务逻辑主要集中在 check() 函数中。当接口的 TPS 超过某个预先设置的最大值时，以及当接口请求出错数大于某个最大允许值时，就会触发告警，通知接口的相关负责人或者团队。 +现在，如果我们需要添加一个功能，当每秒钟接口超时请求个数，超过某个预先设置的最大阈值时，我们也要触发告警发送通知。这个时候，我们该如何改动代码呢？主要的改动有两处：第一处是修改 check() 函数的入参，添加一个新的统计数据 timeoutCount，表示超时接口请求数；第二处是在 check() 函数中添加新的告警逻辑。具体的代码改动如下所示： + +``` +public class Alert { + // ... 省略 AlertRule/Notification 属性和构造函数... + // 改动一：添加参数 timeoutCount + public void check(String api, long requestCount, long errorCount, long timeoutCount) { + long tps = requestCount / durationOfSeconds; + if (tps > rule.getMatchedRule(api).getMaxTps()) { + notification.notify(NotificationEmergencyLevel.URGENCY, "..."); + } + if (errorCount > rule.getMatchedRule(api).getMaxErrorCount()) { + notification.notify(NotificationEmergencyLevel.SEVERE, "..."); + } + // 改动二：添加接口超时处理逻辑 + long timeoutTps = timeoutCount / durationOfSeconds; + if (timeoutTps > rule.getMatchedRule(api).getMaxTimeoutTps()) { + notification.notify(NotificationEmergencyLevel.URGENCY, "..."); + } +} +``` + +这样的代码修改实际上存在挺多问题的: +- 对接口进行了修改，这就意味着调用这个接口的代码都要做相应的修改 +- 修改了 check() 函数，相应的单元测试都需要修改 +因为从本质上来讲，上面的实现是基于修改的方式来实现的新功能，如果遵循开闭原则，该如何实现呢？ +1. 将 check 函数所需要的多个参数封装为 ApiStateInfo 对象 +2. 引入 handler 的概念，将 if 的具体判断逻辑分散到各个 handler 中去 + +``` +public class ApiStatInfo {// 省略 constructor/getter/setter 方法 + private String api; + private long requestCount; + private long errorCount; + private long durationOfSeconds; +} +public class Alert { + private List alertHandlers = new ArrayList<>(); + public void addAlertHandler(AlertHandler alertHandler) { + this.alertHandlers.add(alertHandler); + } + public void check(ApiStatInfo apiStatInfo) { + for (AlertHandler handler : alertHandlers) { + handler.check(apiStatInfo); + } + } +} + +public abstract class AlertHandler { + protected AlertRule rule; + protected Notification notification; + public AlertHandler(AlertRule rule, Notification notification) { + this.rule = rule; + this.notification = notification; + } + public abstract void check(ApiStatInfo apiStatInfo); +} + +public class TpsAlertHandler extends AlertHandler { + public TpsAlertHandler(AlertRule rule, Notification notification) { + super(rule, notification); + } + @Override + public void check(ApiStatInfo apiStatInfo) { + long tps = apiStatInfo.getRequestCount()/ apiStatInfo.getDurationOfSeconds + if (tps > rule.getMatchedRule(apiStatInfo.getApi()).getMaxTps()) { + notification.notify(NotificationEmergencyLevel.URGENCY, "..."); + } + } +} +public class ErrorAlertHandler extends AlertHandler { + public ErrorAlertHandler(AlertRule rule, Notification notification){ + super(rule, notification); + } + @Override + public void check(ApiStatInfo apiStatInfo) { + if (apiStatInfo.getErrorCount() > rule.getMatchedRule(apiStatInfo.getApi()) + notification.notify(NotificationEmergencyLevel.SEVERE, "..."); + } + } +} +``` +使用的地方，创建一个 ApplicationContext 单例类，负责 Alert 的创建、组装（alertRule、notification的注入）、初始化（handlers的添加）逻辑 +``` +public class ApplicationContext { + private AlertRule alertRule; + private Notification notification; + private Alert alert; + public void initializeBeans() { + alertRule = new AlertRule(/*. 省略参数.*/); // 省略一些初始化代码 + notification = new Notification(/*. 省略参数.*/); // 省略一些初始化代码 + alert = new Alert(); + alert.addAlertHandler(new TpsAlertHandler(alertRule, notification)); + alert.addAlertHandler(new ErrorAlertHandler(alertRule, notification)); + } + public Alert getAlert() { return alert; } + // 饿汉式单例 + private static final ApplicationContext instance = new ApplicationContext(); + private ApplicationContext() { + instance.initializeBeans(); + } + public static ApplicationContext getInstance() { + return instance; + } +} + +public class Demo { + public static void main(String[] args) { + ApiStatInfo apiStatInfo = new ApiStatInfo(); + // ... 省略设置 apiStatInfo 数据值的代码 + ApplicationContext.getInstance().getAlert().check(apiStatInfo); + } +} +``` +重构之后的代码要实现：添加一个新的功能，每秒钟接口超时请求个数超过最大阈值就告警，该如何改动？ +1. 在 ApiStatInfo 类中添加新的属性 timeoutCount。 +2. 添加新的 TimeoutAlertHander 类，编写 check 方法 +3. 在 ApplicationContext 类的 initializeBeans() 方法中，往 alert 对象中注册新的 timeoutAlertHandler。 +4. 在使用 Alert 类的时候，需要给 check() 函数的入参 apiStatInfo 对象设置 timeoutCount 的值。 + +``` +public class Alert { // 代码未改动... } + +public class ApiStatInfo {// 省略 constructor/getter/setter 方法 + private String api; + private long requestCount; + private long errorCount; + private long durationOfSeconds; + private long timeoutCount; // 改动一：添加新字段 +} +public abstract class AlertHandler { // 代码未改动... } +public class TpsAlertHandler extends AlertHandler {// 代码未改动...} +public class ErrorAlertHandler extends AlertHandler {// 代码未改动...} +// 改动二：添加新的 handler +public class TimeoutAlertHandler extends AlertHandler {// 省略代码...} + +public class ApplicationContext { + private AlertRule alertRule; + private Notification notification; + private Alert alert; + + public void initializeBeans() { + alertRule = new AlertRule(/*. 省略参数.*/); // 省略一些初始化代码 + notification = new Notification(/*. 省略参数.*/); // 省略一些初始化代码 + alert = new Alert(); + alert.addAlertHandler(new TpsAlertHandler(alertRule, notification)); + alert.addAlertHandler(new ErrorAlertHandler(alertRule, notification)); + // 改动三：注册 handler + alert.addAlertHandler(new TimeoutAlertHandler(alertRule, notification)); + } + //... 省略其他未改动代码... +} + +public class Demo { + public static void main(String[] args) { + ApiStatInfo apiStatInfo = new ApiStatInfo(); + // ... 省略 apiStatInfo 的 set 字段代码 + apiStatInfo.setTimeoutCount(289); // 改动四：设置 tiemoutCount 值 + ApplicationContext.getInstance().getAlert().check(apiStatInfo); + } +} +``` +重构之后的代码更加灵活和易扩展。如果我们要想添加新的告警逻辑，只需要基于扩展的方式创建新的 handler 类即可，不需要改动原来的 check() 函数的逻辑。而且，我们只需要为新的 handler 类添加单元测试，老的单元测试都不会失败，也不用修改。 + +## 修改代码就意味着违背开闭原则吗？ +看了上面重构之后的代码，你可能还会有疑问：在添加新的告警逻辑的时候，尽管改动二（添加新的 handler 类）是基于扩展而非修改的方式来完成的，但改动一、三、四貌似不是基于扩展而是基于修改的方式来完成的，那改动一、三、四不就违背了开闭原则吗？ + +第一：：往 ApiStatInfo 类中添加新的属性 timeoutCount。我们不仅往 ApiStatInfo 类中添加了属性，还添加了对应的 getter/setter 方法。 +那这个问题就转化为：给类中添加新的属性和方法，算作“修改”还是“扩展”？ + +开闭原则的定义：软件实体（模块、类、方法等）应该“对扩展开放、对修改关闭”。从定义中，我们可以看出，开闭原则可以应用在不同粒度的代码中，可以是模块，也可以类，还可以是方法（及其属性）。同样一个代码改动，在粗代码粒度下，被认定为“修改”，在细代码粒度下，又可以被认定为“扩展”。比如，改动一，添加属性和方法相当于修改类，在类这个层面，这个代码改动可以被认定为“修改”；但这个代码改动并没有修改已有的属性和方法，在方法（及其属性）这一层面，它又可以被认定为“扩展”。 + +实际上，我们也没必要纠结某个代码改动是“修改”还是“扩展”，更没必要太纠结它是否违反“开闭原则”。我们回到这条原则的设计初衷：只要它没有破坏原有的代码的正常运行，没有破坏原有的单元测试，我们就可以说，这是一个合格的代码改动。 + +第三和第四：在 ApplicationContext 类的 initializeBeans() 方法中，往 alert 对象中注册新的 timeoutAlertHandler；在使用 Alert 类的时候，需要给 check() 函数的入参 apiStatInfo 对象设置 timeoutCount 的值。 + +这两处改动都是在方法内部进行的，不管从哪个层面（模块、类、方法）来讲，都不能算是“扩展”，而是地地道道的“修改”。不过，有些修改是在所难免的，是可以被接受的。 + +为什么这么说呢？我来解释一下。在重构之后的 Alert 代码中，我们的核心逻辑集中在 Alert 类及其各个 handler 中，当我们在添加新的告警逻辑的时候，Alert 类完全不需要修改，而只需要扩展一个新 handler 类。如果我们把 Alert 类及各个 handler 类合起来看作一个“模块”，那模块本身在添加新的 +功能的时候，完全满足开闭原则。而且，我们要认识到，添加一个新功能，不可能任何模块、类、方法的代码都不“修改”，这个是做不到的。类需要创建、组装、并且做一些初始化操作，才能构建成可运行的的程序，这部分代码的修改是在所难免的。我们要做的是尽量让修改操作更集中、更少、更上层，尽量让最核心、最复杂的那部分逻辑代码满足开闭原则。 + + +## 如何做到“对扩展开放、修改关闭” +为了尽量写出扩展性好的代码，我们要时刻具备扩展意识、抽象意识、封装意识。这些“潜意识”可能比任何开发技巧都重要。 + +在写代码的时候后，我们要多花点时间往前多思考一下，这段代码未来可能有哪些需求变更、如何设计代码结构，事先留好扩展点，以便在未来需求变更的时候，不需要改动代码整体结构、做到最小代码改动的情况下，新的代码能够很灵活地插入到扩展点上，做到“对扩展开放、对修改关闭”。 + +还有，在识别出代码可变部分和不可变部分之后，我们要将可变部分封装起来，隔离变化，提供抽象化的不可变接口，给上层系统使用。当具体的实现发生变化的时候，我们只需要基于相同的抽象接口，扩展一个新的实现，替换掉老的实现即可，上游系统的代码几乎不需要修改。 diff --git a/Chapter6 - Design Pattern/6.5.md b/Chapter6 - Design Pattern/6.5.md new file mode 100644 index 0000000..35b4be9 --- /dev/null +++ b/Chapter6 - Design Pattern/6.5.md @@ -0,0 +1,96 @@ +# SOLID之里氏替换 + +里式替换原则的英文翻译是：Liskov Substitution Principle，缩写为 LSP。这个原则最早 +是在 1986 年由 Barbara Liskov 提出，他是这么描述这条原则的： + +> If S is a subtype of T, then objects of type T may be replaced with objects of type S, without breaking the program。 + +在 1996 年，Robert Martin 在他的 SOLID 原则中，重新描述了这个原则，英文原话是这 +样的： + +> Functions that use pointers of references to base classes must be able to use objects of derived classes without knowing it。 + +子类对象（object of subtype/derived class）能够替换程序（program）中父类对（object of base/parent class）出现的任何地方，并且保证原来程序的逻辑行为（behavior）不变及正确性不被破坏。 + +父类 Transporter 使用 org.apache.http 库中的 HttpClient 类来传输网络数据。子类 SecurityTransporter 继承父类 Transporter，增加了额外的功能，支持传输 appId 和 appToken 安全认证信息。 + +``` +public class Transporter { + private HttpClient httpClient; + public Transporter(HttpClient httpClient) { + this.httpClient = httpClient; + } + public Response sendRequest(Request request) { + // ...use httpClient to send request + } +} + + +public class SecurityTransporter extends Transporter { + private String appId; + private String appToken; + public SecurityTransporter(HttpClient httpClient, String appId, String appToken) { + super(httpClient); + this.appId = appId; + this.appToken = appToken; + } + + @Override + public Response sendRequest(Request request) { + if (StringUtils.isNotBlank(appId) && StringUtils.isNotBlank(appToken)) { + request.addPayload("app-id", appId); + request.addPayload("app-token", appToken); + } + return super.sendRequest(request); + } +} + +public void demoFunction(Transporter transporter) { + Reuqest request = new Request(); + //... 省略设置 request 中数据值的代码... + Response response = transporter.sendRequest(request); +} + +// 里式替换原则 +Demo demo = new Demo(); +demo.demofunction(new SecurityTransporter(/* 省略参数 */);); +``` +在上面的代码中，子类 SecurityTransporter 的设计完全符合里式替换原则，可以替换父类出现的任何位置，并且原来代码的逻辑行为不变且正确性也没有被破坏。看上去里氏替换原则和多态没啥差别。继续看下面的例子 + +SecurityTransporter 类中 sendRequest() 函数稍加改造一下。改造前，如果 appId 或者 appToken 没有设置，我们就不做校验；改造后，如果 appId 或者 appToken 没有设置，则直接抛出 NoAuthorizationRuntimeException 未授权异常 +``` +public class SecurityTransporter extends Transporter { + //... 省略其他代码.. + @Override + public Response sendRequest(Request request) { + if (StringUtils.isBlank(appId) || StringUtils.isBlank(appToken)) { + throw new NoAuthorizationRuntimeException(...); + } + request.addPayload("app-id", appId); + request.addPayload("app-token", appToken); + return super.sendRequest(request); + } +} +``` +在改造之后的代码中，如果传递进 demoFunction() 函数的是父类 Transporter 对象，那 demoFunction() 函数并不会有异常抛出，但如果传递给 demoFunction() 函数的是子类 SecurityTransporter 对象，那 demoFunction() 有可能会有异常抛出。尽管代码中抛出的是运行时异常（Runtime Exception），我们可以不在代码中显式地捕获处理，但子类替换父类传递进 demoFunction 函数之后，整个程序的逻辑行为有了改变。 + +虽然从定义描述和代码实现上来看，多态和里式替换有点类似，但它们关注的角度是不一样的。多态是面向对象编程的一大特性，也是面向对象编程语言的一种语法。它是一种代码实现的思路。而里式替换是一种设计原则，是用来指导继承关系中子类该如何设计的，子类的设计要保证在替换父类的时候，不改变原有程序的逻辑以及不破 +坏原有程序的正确性。 + + +## 如何判断是不是违背里氏替换原则 + +里式替换原则还有另外一个更加能落地、更有指导意义的描述，那就是“DesignBy Contract”，中文翻译就是“按照协议来设计”。 + +子类在设计的时候，要遵守父类的行为约定（或者叫协议）。父类定义了函数的行为约定，那子类可以改变函数的内部实现逻辑，但不能改变函数原有的行为约定。这里的行为约定包括：函数声明要实现的功能；对输入、输出、异常的约定；甚至包括注释中所罗列的任何特殊说明。实际上，定义中父类和子类之间的关系，也可以替换成接口和实现类之间的关系。 + +### 子类违背父类声明要实现的功能 +父类中提供的 sortOrdersByAmount() 订单排序函数，是按照金额从小到大来给订单排序的，而子类重写这个 sortOrdersByAmount() 订单排序函数之后，是按照创建日期来给订单排序的。那子类的设计就违背里式替换原则。 +### 子类违背父类对输入、输出、异常的约定 +在父类中，某个函数约定：运行出错的时候返回 null；获取数据为空的时候返回空集合（empty collection）。而子类重载函数之后，实现变了，运行出错返回异常（exception），获取不到数据返回 null。那子类的设计就违背里式替换原则。在父类中，某个函数约定，输入数据可以是任意整数，但子类实现的时候，只允许输入数据是正整数，负数就抛出，也就是说，子类对输入的数据的校验比父类更加严格，那子类的设计就违背了里式替换原则。在父类中，某个函数约定，只会抛出 ArgumentNullException 异常，那子类的设计实现中只允许抛出 ArgumentNullException 异常，任何其他异常的抛出，都会导致子类违背里式替换原则。 + + +### 子类违背父类注释中所罗列的任何特殊说明 +父类中定义的 withdraw() 提现函数的注释是这么写的：“用户的提现金额不得超过账户余额......”，而子类重写 withdraw() 函数之后，针对 VIP 账号实现了透支提现的功能，也就是提现金额可以大于账户余额，那这个子类的设计也是不符合里式替换原则的。 + +以上便是三种典型的违背里式替换原则的情况。除此之外，判断子类的设计实现是否违背里式替换原则，还有一个小窍门，那就是拿父类的单元测试去验证子类的代码。如果某些单元测试运行失败，就有可能说明，子类的设计实现没有完全地遵守父类的约定，子类有可能违背了里式替换原则。 \ No newline at end of file diff --git a/Chapter6 - Design Pattern/6.6.md b/Chapter6 - Design Pattern/6.6.md new file mode 100644 index 0000000..2e99d95 --- /dev/null +++ b/Chapter6 - Design Pattern/6.6.md @@ -0,0 +1,58 @@ +# SOLID之接口隔离原则 + +## 定义 +接口隔离原则“Interface Segregation Principle”，ISP。Robert Martin 在 SOLID 原则中是这样定义它的：“Clients should not be forced to depend upon interfaces that they do not use。”直译成中文的话就是：客户端不应该强迫依赖它不需要的接口。其中的“客户端”，可以理解为接口的调用者或者使用者。 + +微服务用户系统提供了一组跟用户相关的 API 给其他系统使用，比如：注册、登录、获取用户信息等。具体代码如下所示： + +``` +public interface UserService { + boolean register(String cellphone, String password); + boolean login(String cellphone, String password); + UserInfo getUserInfoById(long id); + UserInfo getUserInfoByCellphone(String cellphone); +} +public class UserServiceImpl implements UserService { + //... +} +``` + +如果需要一个删除账户的功能，如何处理？是不是直接给 UserService 中添加一个 deleteUserByPhone 就可以。但存在一个安全隐患。 + +删除用户是一个非常慎重的操作，我们只希望通过后台管理系统来执行，所以这个接口只限于给后台管理系统使用。如果我们把它放到 UserService 中，那所有使用到 UserService 的系统，都可以调用这个接口。不加限制地被其他业务系统调用，就有可能导致误删用户。 + +当然，最好的解决方案是从架构设计的层面，通过接口鉴权的方式来限制接口的调用。不过，如果暂时没有鉴权框架来支持，我们还可以从代码设计的层面，尽量避免接口被误用。 + +我们参照接口隔离原则，调用者不应该强迫依赖它不需要的接口，将删除接口单独放到另外一个接口 RestrictedUserService 中，然后将 RestrictedUserService 只打包提供给后台管 +理系统来使用。具体的代码实现如下所示： +``` +public interface UserService { + boolean register(String cellphone, String password); + boolean login(String cellphone, String password); + UserInfo getUserInfoById(long id); + UserInfo getUserInfoByCellphone(String cellphone); +} +public interface RestrictedUserService { + boolean deleteUserByCellphone(String cellphone); + boolean deleteUserById(long id); +} +public class UserServiceImpl implements UserService, RestrictedUserService { + // ... 省略实现代码... +} +``` + +在刚刚的这个例子中，我们把接口隔离原则中的接口，理解为一组接口集合，它可以是某个微服务的接口，也可以是某个类库的接口等等。在设计微服务或者类库接口的时候，如果部分接口只被部分调用者使用，那我们就需要将这部分接口隔离出来，单独给对应的调用者使用，而不是强迫其他调用者也依赖这部分不会被用到的接口。 + +## 理解 +如何理解“接口隔离原则”？ + +如果把“接口”理解为一组接口集合，可以是某个微服务的接口，也可以是某个类库的接口等。如果部分接口只被部分调用者使用，我们就需要将这部分接口隔离出来，单独给这部分调用者使用，而不强迫其他调用者也依赖这部分不会被用到的接口。 + +如果把“接口”理解为单个 API 接口或函数，部分调用者只需要函数中的部分功能，那我们就需要把函数拆分成粒度更细的多个函数，让调用者只依赖它需要的那个细粒度函数。 + +如果把“接口”理解为 OOP 中的接口，也可以理解为面向对象编程语言中的接口语法。那接口的设计要尽量单一，不要让接口的实现类和调用者，依赖不需要的接口函数。 + +接口隔离原则与单一职责原则的区别？ + +单一职责原则针对的是模块、类、接口的设计。接口隔离原则相对于单一职责原则，一方面更侧重于接口的设计，另一方面它的思考角度也是不同的。接口隔离原则提供了一种判断接口的职责是否单一的标准：通过调用者如何使用接口来间接地判定。如果调用者只使用部分接口或接口的部分功能，那接口的设计就不够职责单一。 + diff --git a/Chapter6 - Design Pattern/6.7.md b/Chapter6 - Design Pattern/6.7.md new file mode 100644 index 0000000..4549072 --- /dev/null +++ b/Chapter6 - Design Pattern/6.7.md @@ -0,0 +1,7 @@ +# SOLID之依赖反转原则 +依赖反转原则的英文翻译是 Dependency Inversion Principle，缩写为 DIP。中文翻译有时候也叫依赖倒置原则。 + +> High-level modules shouldn’t depend on low-level modules. Both modules should depend on abstractions. In addition, abstractions shouldn’t depend on details. Details depend on abstractions. + +高层模块不应该依赖低层模块，高层模块和低层模块都应通过抽象来互相依赖。抽象不要依赖具体的实现细节，具体的实现细节应该依赖抽象。 + diff --git a/Chapter6 - Design Pattern/6.8.md b/Chapter6 - Design Pattern/6.8.md new file mode 100644 index 0000000..c3266b8 --- /dev/null +++ b/Chapter6 - Design Pattern/6.8.md @@ -0,0 +1,82 @@ +# 聊聊重构 + +> 什么情况下要重构？到底重构什么？又该如何重构？为了保证重构不出错，有哪些有效的技术手段？ + +重构代码对一个工程师能力的要求，要比单纯写代码高得多。重构需要你能洞察出代码存在的坏味道或者设计上的不足，并且能合理、熟练地利用设计思想、原则、模式、编程规范等理论知识解决这些问题。 + + + +## 重构的目的：为什么要重构（why）？ +软件设计大师 Martin Fowler 是这样定义重构的：“重构是一种对软件内部结构的改善，目的是在不改变软件的可见行为的情况下，使其更易理解，修改成本更低。” + +重构不改变外部的可见行为”。我们可以把重构理解为，在保持功能不变的前提下，利用设计思想、原则、模式、编程规范等理论来优化代码，修改设计上的不足，提高代码质量。 + + +## 为什么要进行代码重构？ +重构是时刻保证代码质量的一个极其有效的手段，不至于让代码腐化到无可救药的地步。项目在演进，代码不停地在堆砌。如果没有人为代码的质量负责任，代码总是会往越来越混乱的方向演进。当混乱到一定程度之后，量变引起质变，项目的维护成本已经高过重新开发一套新代码的成本，想要再去重构，已经没有人能做到了。 + +优秀的代码或架构不是一开始就能完全设计好的，就像优秀的公司和产品也都是迭代出来的。我们无法 100% 遇见未来的需求，也没有足够的精力、时间、资源为遥远的未来买单，所以，随着系统的演进，重构代码也是不可避免的。 + +最后，重构是避免过度设计的有效手段。在我们维护代码的过程中，真正遇到问题的时候，再对代码进行重构，能有效避免前期投入太多时间做过度的设计，做到有的放矢 + +重构对一个工程师本身技术的成长也有重要的意义。重构实际上是对我们学习的经典设计思想、设计原则、设计模式、编程规范的一种应用。重构实际上就是将这些理论知识，应用到实践的一个很好的场景，能够锻炼我们熟练使用这些理论知识的能力。除此之外，平时堆砌业务逻辑，你可能总觉得没啥成长，而将一个比较烂的代码重构成一个比较好的代码，会让你很有成就感。 + +## 重构的对象：到底重构什么（what）？ +根据重构的规模，我们可以笼统地分为大规模高层次重构（以下简称为“大型重构”）和小规模低层次的重构（以下简称为“小型重构”）。 + +大型重构指的是对顶层代码设计的重构，包括：系统、模块、代码结构、类与类之间的关系等的重构，重构的手段有：分层、模块化、解耦、抽象可复用组件等等。这类重构的工具就是我们学习过的那些设计思想、原则和模式。这类重构涉及的代码改动会比较多，影响面会比较大，所以难度也较大，耗时会比较长，引入 bug 的风险也会相对比较大。 + +小型重构指的是对代码细节的重构，主要是针对类、函数、变量等代码级别的重构，比如规范命名、规范注释、消除超大类或函数、提取重复代码等等。小型重构更多的是利用我们能后面要讲到的编码规范。这类重构要修改的地方比较集中，比较简单，可操作性较强，耗时会比较短，引入 bug 的风险相对来说也会比较小。你只需要熟练掌握各种编码规范，就可以做到得心应手。 + + +## 重构的时机：什么时候重构（when）？ +代码烂到一定程度之后才去重构吗？当然不是。因为当代码真的烂到出现“开发效率低，招了很多人，天天加班，出活却不多，线上 bug 频发。这时候可能就是积重难返了。 + +所以推崇在项目开发或者系统开发的过程中，保持设计和一些思想，写出优雅的代码。持续不断的小重构。 + +要有 Owner 意识，平时项目不那么紧张的时候，就可以看看项目中有哪些写得不够好的、可以优化的代码，主动去重构一下。或者，在修改、添加某个功能代码的时候，可以顺手把不符合编码规范、不好的设计重构一下。总之，就像把单元测试、Code Review 作为开发的一部分，我们如果能把持续重构也作为开发的一部分，成为一种开发习惯，对项目、对自己都会很有好处。 + +尽管我们说重构能力很重要，但持续重构意识更重要。我们要正确地看待代码质量和重构这件事情。技术在更新、需求在变化、人员在流动，代码质量总会在下降，代码总会存在不完美，重构就会持续在进行。时刻具有持续重构意识，才能避免开发初期就过度设计，避免代码维护的过程中质量的下降。而那些看到别人代码有点瑕疵就一顿乱骂，或者花尽心思去构思一个完美设计的人，往往都是因为没有树立正确的代码质量观，没有持续重构意识。 + +## 如何重构？ +按照重构的规模，重构可以笼统地分为大型重构和小型重构。对于这两种不同规模的重构，我们要区别对待。 + +对于大型重构来说，因为涉及的模块、代码会比较多，如果项目代码质量又比较差，耦合比较严重，往往会牵一发而动全身，本来觉得一天就能完成的重构，你会发现越改越多、越改越乱，没一两个礼拜都搞不定。而新的业务开发又与重构相冲突，最后只能半途而废，revert 掉所有的改动，很失落地又去堆砌烂代码了 + +所以最好事先做好重构规划，每个节点交付小的重构结果，进行测试、验证，趁着项目的测试资源，没问题之后进行下一阶段的重构，保证代码持续可运行、可测试、逻辑正确的状态。按照规划，一小部分进行重构，可以保证项目正常交付、也可以趁着测试资源、也不会 delay 正常项目，不会和正在开发的新 feature 进行冲突。 + + +## 重构的质量保证 +除了 QA 测试之外，最有效、可落地的测试就是单元测试可。当重构完成后，如果新的代码可通过单元测试所有 case，那么说明之前的逻辑没有被破坏，原有系统的行为、外部可见性没有改变。 + +那 iOS 侧如何开展单元测试，可以见[这篇文章](./../Chapter1%20-%20iOS/1.75.md) + +## 代码是否需要“解耦”？ +间接的衡量标准有很多，比如，看修改代码是否牵一发而动全身。直接的衡量标准是把模块与模块、类与类之间的依赖关系画出来，根据依赖关系图的复杂性来判断是否需要解耦重构。 + +## 如何解耦 +软件设计与开发最重要的工作之一就是应对复杂性。人处理复杂性的能力是有限的。过于复杂的代码往往在可读性、可维护性上都不友好。那如何来控制代码的复杂性呢？手段有很多，我个人认为，最关键的就是解耦，保证代码松耦合、高内聚。如果说重构是保证代码质量不至于腐化到无可救药地步的有效手段，那么利用解耦的方法对代码重构，就是保证代码不至于复杂到无法控制的有效手段。 + +代码“高内聚、松耦合”，也就意味着，代码结构清晰、分层和模块化合理、依赖关系简单、模块或类之间的耦合小，那代码整体的质量就不会差。即便某个具体的类或者模块设计得不怎么合理，代码质量不怎么高，影响的范围是非常有限的。我们可以聚焦于这个模块或者类，做相应的小型重构。而相对于代码结构的调整，这种改动范围比较集中的小型重构的难度就容易多了。 + +1. 封装与抽象 +2. 中间层 +3. 模块化 +4. 其他设计思想和原则 + +单一职责原则 + +内聚性和耦合性并非独立的。高内聚会让代码更加松耦合，而实现高内聚的重要指导原则就是单一职责原则。模块或者类的职责设计得单一，而不是大而全，那依赖它 +的类和它依赖的类就会比较少，代码耦合也就相应的降低了。 + +基于接口而非实现编程 +基于接口而非实现编程能通过接口这样一个中间层，隔离变化和具体的实现。这样做的好处是，在有依赖关系的两个模块或类之间，一个模块或者类的改动，不会影响到另一个模块或类。实际上，这就相当于将一种强依赖关系（强耦合）解耦为了弱依赖关系（弱耦合）。 + +依赖注入 +跟基于接口而非实现编程思想类似，依赖注入也是将代码之间的强耦合变为弱耦合。尽管依赖注入无法将本应该有依赖关系的两个类，解耦为没有依赖关系，但可以让耦合关系没那么紧密，容易做到插拔替换。 + +多用组合少用继承 +继承是一种强依赖关系，父类与子类高度耦合，且这种耦合关系非常脆弱，牵一发而动全身，父类的每一次改动都会影响所有的子类。相反，组合关系是一种弱依赖关系，这种关系更加灵活，所以，对于继承结构比较复杂的代码，利用组合来替换继承，也是一种解耦的有效手段。 + +迪米特法则 +迪米特法则讲的是，不该有直接依赖关系的类之间，不要有依赖；有依赖关系的类之间，尽量只依赖必要的接口。从定义上，我们明显可以看出，这条原则的目的就是为了实现代码的松耦合。 diff --git a/Chapter6 - Design Pattern/6.9.md b/Chapter6 - Design Pattern/6.9.md new file mode 100644 index 0000000..bf38f5e --- /dev/null +++ b/Chapter6 - Design Pattern/6.9.md @@ -0,0 +1,209 @@ +# 单例模式 + +> 为什么要使用单例？ +单例存在哪些问题？ +单例与静态类的区别？ +有何替代的解决方案？ + +## 为什么要使用单例？ + +创建型模式主要解决对象的创建问题，封装复杂的创建过程，解耦对象的创建代码和使用代码。其中单例模式、工厂模式、建造者模式、原型模式都是创建型模式。 + +单例设计模式（Singleton Design Pattern）理解起来非常简单。一个类只允许创建一个对象（或者实例），那这个类就是一个单例类，这种设计模式就叫作单例设计模式，简称单例模式。 + +### 处理资源访问冲突 +我们先来看第一个例子。在这个例子中，我们自定义实现了一个往文件中打印日志的 Logger 类。具体的代码实现如下所示： +``` +public class Logger { + private FileWriter writer; + public Logger() { + File file = new File("/Users/meiying/log.txt"); + writer = new FileWriter(file, true); //true表示追加写入 + } + public void log(String message) { + writer.write(mesasge); + } +} +// Logger类的应用示例： +public class UserController { + private Logger logger = new Logger(); + public void login(String username, String password) { + // ...省略业务逻辑代码... + logger.log(username + " logined!"); + } +} +public class OrderController { + private Logger logger = new Logger(); + public void create(OrderVo order) { + // ...省略业务逻辑代码... + logger.log("Created an order: " + order.toString()); + } +} +``` +在上面的代码中，我们注意到，所有的日志都写入到同一个文件 /Users/meiying/log.txt 中。在 UserController 和 OrderController 中，我们分别创 +建两个 Logger 对象。在 Web 容器的 Servlet 多线程环境下，如果两个 Servlet 线程同时分别执行 login() 和 create() 两个函数，并且同时写日志到 log.txt 文件中，那就有可能存在日志信息互相覆盖的情况 + +那如何来解决这个问题呢？我们最先想到的就是通过加锁的方式：给 log() 函数加互斥锁（Java 中可以通过 synchronized 的关键字），同一时刻只允许一个线程调用执行 log()函数。具体的代码实现如下所示： + +``` +public class Logger { + private FileWriter writer; + public Logger() { + File file = new File("/Users/wangzheng/log.txt"); + writer = new FileWriter(file, true); //true表示追加写入 + } + public void log(String message) { + synchronized(this) { + writer.write(mesasge); + } + } +} +``` +可以解决问题吗？不会。因为这种锁是一个对象级别的锁，一个对象在不同的线程下同时调用 log() 函数，会被强制要求顺序执行。但是，不同的对象之间并不共享同一把锁。在不同的线程下，通过不同的对象调用执行 log() 函数，锁并不会起作用，仍然有可能存在写入日志互相覆盖的问题 + +实际上，要想解决这个问题也不难，我们只需要把对象级别的锁，换成类级别的锁就可以了。让所有的对象都共享同一把锁。这样就避免了不同对象之间同时调用 log() 函数，而导致的日志覆盖问题。具体的代码实现如下所 + +``` +public void log(String message) { + synchronized(Logger.class) { // 类级别的锁 + writer.write(mesasge); + } +} +``` +除了使用类级别锁之外，实际上，解决资源竞争问题的办法还有很多，分布式锁是最常听到的一种解决方案。不过，实现一个安全可靠、无 bug、高性能的分布式锁，并不是件容易的事情。除此之外，并发队列（比如 Java 中的 BlockingQueue）也可以解决这个问题：多个线程同时往并发队列里写日志，一个单独的线程负责将并发队列中的数据，写入到日志文件。这种方式实现起来也稍微有点复杂。 + +相对于这两种解决方案，单例模式的解决思路就简单一些了。单例模式相对于之前类级别锁的好处是，不用创建那么多 Logger 对象，一方面节省内存空间，另一方面节省系统文件句柄（对于操作系统来说，文件句柄也是一种资源，不能随便浪费）。 + +我们将 Logger 设计成一个单例类，程序中只允许创建一个 Logger 对象，所有的线程共享使用的这一个 Logger 对象，共享一个 FileWriter 对象，而 FileWriter 本身是对象级别线程安全的，也就避免了多线程情况下写日志会互相覆盖的问题。按照这个设计思路，我们实现了 Logger 单例类。具体代码如下所示： +``` +public class Logger { + private FileWriter writer; + private static final Logger instance = new Logger(); + private Logger() { + File file = new File("/Users/wangzheng/log.txt"); + writer = new FileWriter(file, true); //true表示追加写入 + } + public static Logger getInstance() { + return instance; + } + public void log(String message) { + writer.write(mesasge); + } +} + +// Logger类的应用示例： +public class UserController { + public void login(String username, String password) { + // ...省略业务逻辑代码... + Logger.getInstance().log(username + " logined!"); + } +} +public class OrderController { + private Logger logger = new Logger(); + public void create(OrderVo order) { + // ...省略业务逻辑代码... + Logger.getInstance().log("Created a order: " + order.toString()); + } +} +``` + +### 表示全局唯一类 +如果有些数据在系统中只应保存一份，那就比较适合设计为单例类。比如，配置信息类。在系统中，我们只有一个配置文件，当配置文件被加载到内存之后，以 +对象的形式存在，也理所应当只有一份。 + +再比如，唯一递增 ID 号码生成器。如果程序中有两个对象，那就会存在生成重复 ID 的情况，所以，我们应该将 ID 生成器类设计为单例 + + +## 如何实现一个单例 +### 饿汉式 +饿汉式的实现方式比较简单。在类加载的时候，instance 静态实例就已经创建并初始化好了，所以，instance 实例的创建过程是线程安全的。不过，这样的实现方式不支持延迟加载（在真正用到 IdGenerator 的时候，再创建实例），从名字中我们也可以看出这一点。具体的代码实现如下所示： +``` +public class IdGenerator { + private AtomicLong id = new AtomicLong(0); + private static final IdGenerator instance = new IdGenerator(); + private IdGenerator() {} + public static IdGenerator getInstance() { + return instance; + } + public long getId() { + return id.incrementAndGet(); + } +} +``` +有人觉得这种实现方式不好，因为不支持延迟加载，如果实例占用资源多（比如占用内存多）或初始化耗时长（比如需要加载各种配置文件），提前初始化实例是一种浪费资源的行为。最好的方法应该在用到的时候再去初始化 + +如果初始化耗时长，那我们最好不要等到真正要用它的时候，才去执行这个耗时长的初始化过程，这会影响到系统的性能（比如，在响应客户端接口请求的时候，做这个初始化操作，会导致此请求的响应时间变长，甚至超时）。采用饿汉式实现方式，将耗时的初始化操作，提前到程序启动的时候完成，这样就能避免在程序运行的时候，再去初始化导致的性能问题。 + +如果实例占用资源多，按照 fail-fast 的设计原则（有问题及早暴露），那我们也希望在程序启动时就将这个实例初始化好。如果资源不够，就会在程序启动的时候触发报错（比如Java 中的 PermGen Space OOM），我们可以立即去修复。这样也能避免在程序运行一段时间后，突然因为初始化这个实例占用资源过多，导致系统崩溃，影响系统的可用性 + +### 懒汉式 +懒汉式相对于饿汉式的优势是支持延迟加载。具体的代码实现如下所示： +``` +public class IdGenerator { + private AtomicLong id = new AtomicLong(0); + private static IdGenerator instance; + private IdGenerator() {} + public static synchronized IdGenerator getInstance() { + if (instance == null) { + instance = new IdGenerator(); + } + return instance; + } + public long getId() { + return id.incrementAndGet(); + } +} +``` +不过懒汉式的缺点也很明显，我们给 getInstance() 这个方法加了一把大锁（synchronzed），导致这个函数的并发度很低。量化一下的话，并发度是 1，也就相当于串行操作了。而这个函数是在单例使用期间，一直会被调用。如果这个单例类偶尔会被用到，那这种实现方式还可以接受。但是，如果频繁地用到，那频繁加锁、释放锁及并发度低等问题，会导致性能瓶颈，这种实现方式就不可取了 + + +### 双重检测 +饿汉式不支持延迟加载，懒汉式有性能问题，不支持高并发。那我们再来看一种既支持延迟加载、又支持高并发的单例实现方式，也就是双重检测实现方式。 +在这种实现方式中，只要 instance 被创建之后，即便再调用 getInstance() 函数也不会再进入到加锁逻辑中了。所以，这种实现方式解决了懒汉式并发度低的问题。具体的代码实现如下所示： + +``` +public class IdGenerator { + private AtomicLong id = new AtomicLong(0); + private static IdGenerator instance; + private IdGenerator() {} + public static IdGenerator getInstance() { + if (instance == null) { + synchronized(IdGenerator.class) { // 此处为类级别的锁 + if (instance == null) { + instance = new IdGenerator(); + } + } + } + return instance; + } + public long getId() { + return id.incrementAndGet(); + } +} +``` +网上有人说，这种实现方式有些问题。因为指令重排序，可能会导致 IdGenerator 对象被new 出来，并且赋值给 instance 之后，还没来得及初始化（执行构造函数中的代码逻辑），就被另一个线程使用了。 + +要解决这个问题，我们需要给 instance 成员变量加上 volatile 关键字，禁止指令重排序才行。实际上，只有很低版本的 Java 才会有这个问题。我们现在用的高版本的 Java 已经在 JDK 内部实现中解决了这个问题（解决的方法很简单，只要把对象 new 操作和初始化操作设计为原子操作，就自然能禁止重排序 + +### 静态内部类 +我们再来看一种比双重检测更加简单的实现方法，那就是利用 Java 的静态内部类。它有点类似饿汉式，但又能做到了延迟加载。具体是怎么做到的呢？我们先来看它的代码实现。 +``` +public class IdGenerator { + private AtomicLong id = new AtomicLong(0); + private IdGenerator() {} + private static class SingletonHolder { + private static final IdGenerator instance = new IdGenerator(); + } + public static IdGenerator getInstance() { + return SingletonHolder.instance; + } + public long getId() { + return id.incrementAndGet(); + } +} +``` +SingletonHolder 是一个静态内部类，当外部类 IdGenerator 被加载的时候，并不会创建 SingletonHolder 实例对象。只有当调用 getInstance() 方法时，SingletonHolder 才会被加载，这个时候才会创建 instance。insance 的唯一性、创建过程的线程安全性，都由 JVM 来保证。所以，这种实现方法既保证了线程安全，又能做到延迟加载 + +## 如何理解单例模式的唯一性 +“一个类只允许创建唯一一个对象（或者实例），那这个类就是一个单例类，这种设计模式就叫作单例设计模式，简称单例模式。定义中提到，“一个类只允许创建唯一一个对象”。那对象的唯一性的作用范围是什么呢？是指线程内只允许创建一个对象，还是指进程内只允许创建一个对象？答案是后者，也就是说，单例模式创建的对象是进程唯一的 + diff --git a/Chapter6 - Design Pattern/chapter6.md b/Chapter6 - Design Pattern/chapter6.md index e18dfdd..b41c5aa 100644 --- a/Chapter6 - Design Pattern/chapter6.md +++ b/Chapter6 - Design Pattern/chapter6.md @@ -4,5 +4,29 @@ 第六部分主要介绍设计模式相关的概念和思考 * [1、声明式与命令式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.1.md) + * [2、面向对象 ](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.2.md) + * [3、SOLID之单一职责 SRP](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.3.md) + * [4、SOLID之开闭原则](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.4.md) + * [5、SOLID之里氏替换](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.5.md) + * [6、SOLID之接口隔离原则](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.6.md) + * [7、SOLID之依赖反转原则](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.7.md) + * [8、聊聊重构](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.8.md) + * [9、单例模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.9.md) + * [10、工厂模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.10.md) + * [11、建造者模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.11.md) + * [12、原型模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.12.md) + * [13、代理模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.13.md) + * [14、桥接模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.14.md) + * [15、装饰器模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.15.md) + * [16、适配器模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.16.md) + * [17、门面模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.17.md) + * [18、组合模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.18.md) + * [19、享元模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.19.md) + * [20、观察者模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.20.md) + * [21、模板模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.21.md) + * [22、模板模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.22.md) + * [23、职责链模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.23.md) + + \ No newline at end of file diff --git a/SUMMARY.md b/SUMMARY.md index 3cdb1fc..f20e6ce 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -184,6 +184,28 @@ * [Chapter6 - Design Pattern](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/chapter7.md) * [1、声明式与命令式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.1.md) + * [2、面向对象 ](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.2.md) + * [3、SOLID之单一职责 SRP](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.3.md) + * [4、SOLID之开闭原则](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.4.md) + * [5、SOLID之里氏替换](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.5.md) + * [6、SOLID之接口隔离原则](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.6.md) + * [7、SOLID之依赖反转原则](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.7.md) + * [8、聊聊重构](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.8.md) + * [9、单例模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.9.md) + * [10、工厂模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.10.md) + * [11、建造者模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.11.md) + * [12、原型模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.12.md) + * [13、代理模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.13.md) + * [14、桥接模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.14.md) + * [15、装饰器模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.15.md) + * [16、适配器模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.16.md) + * [17、门面模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.17.md) + * [18、组合模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.18.md) + * [19、享元模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.19.md) + * [20、观察者模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.20.md) + * [21、模板模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.21.md) + * [22、模板模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.22.md) + * [23、职责链模式](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter6%20-%20Design%20Pattern/6.23.md) * [Chapter7 - Geek Talk](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter7%20-%20Geek%20Talk/chapter7.md) * [1、命令行文件查找](https://github.com/FantasticLBP/knowledge-kit/blob/master/Chapter7%20-%20Geek%20Talk/7.1.md) diff --git a/assets/EventBus-ObserverRegisterTable.png b/assets/EventBus-ObserverRegisterTable.png new file mode 100644 index 0000000000000000000000000000000000000000..fd00140cbe7c6bf1c5359e8f9c51eb997c894b80 GIT binary patch literal 59681 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

;q{DEqig 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