feed.xml

<?xml version="1.0" encoding="utf-8"?><feed xmlns="http://www.w3.org/2005/Atom" xml:lang="zh_CN"><generator uri="https://jekyllrb.com/" version="4.2.1">Jekyll</generator><link href="https://www.desgard.com/feed.xml" rel="self" type="application/atom+xml" /><link href="https://www.desgard.com/" rel="alternate" type="text/html" hreflang="zh_CN" /><updated>2023-09-14T20:18:23-08:00</updated><id>https://www.desgard.com/feed.xml</id><title type="html">一片瓜田</title><subtitle>I write more code to write less.
</subtitle><author><name>冬瓜</name><email>gua@desgard.com</email></author><entry><title type="html">WWDC23 - What’s new in Swift</title><link href="https://www.desgard.com/2023/06/21/what's_new_in_swfit_2023.html" rel="alternate" type="text/html" title="WWDC23 - What’s new in Swift" /><published>2023-06-21T00:00:00-08:00</published><updated>2023-06-21T00:00:00-08:00</updated><id>https://www.desgard.com/2023/06/21/what's_new_in_swfit_2023</id><content type="html" xml:base="https://www.desgard.com/2023/06/21/what's_new_in_swfit_2023.html"><![CDATA[<blockquote>
  <p>摘要：这个 Session 涉及了 Swift 的新语法特性和 Swift Macro 的话题，这些功能对于编写更加灵活和健壮的 API 以及高质量代码起到了很大的帮助。此外，也深入探讨了在受限环境下使用 Swift 的优势，并讨论了 Swift 在适配多种平台设备和语言方面的灵活性。</p>
</blockquote>

<p>本文基于 <a href="https://developer.apple.com/videos/play/wwdc2023/10164/">Session 10164</a> 梳理。</p>

<blockquote>
  <p>审核：</p>

  <ul>
    <li>
      <p>stevapple：学生，Swift/Vapor 社区贡献者</p>
    </li>
    <li>
      <p>kemchenj：老司机技术核心成员 / 开源爱好者 / 最近在做 3D 重建相关的开发工作</p>
    </li>
  </ul>
</blockquote>

<p>今年是 Swift 的一次重大更新，这个 Session 将和大家一起聊聊 Swift 语言今年的一些改进、简洁的语法糖以及一些强大的新 API 的使用。一年前，Swift 项目的核心团队宣布了成立 Language Steering Group ，主要负责监督 Swift 语言和标准库的修改。从这之后，Language Steering Group 已经审核了 40 多个新的提案，这些会覆盖到我们今天所要讨论的几个。</p>

<p>有很多社区提案都有相同的思路和看法，所以我们会将这些类似的提案进行合并。而在这之中，Swift Macro（在 C 的中文教材中，一般称作<strong>宏</strong>，下文继续使用 Macro 进行代替）是提及最多的一个提案，所以我们后文也会具体讨论 Swift 5.9 中关于 Swift Macro 的新特性。</p>

<p>当然，语言的演进只是 Swift 社区工作的一部分，一门成功的语言需要的远不止这些，它还需要配合优秀的工具链、多平台的强大支持以及丰富的文档。为了全方位的监控进展，核心团队也正在组建一个 Ecosystem Steering Group ，这个新的团队也在 swift.org 的博客中有所提及，我们可以一起期待一下这个团队的进一步公告。</p>

<p>现在我们进入正题，来讨论一下今年 Swift 语言的更新。</p>

<h2 id="ifelse-和-switch-语句表达式"><code class="language-plaintext highlighter-rouge">if/else</code> 和 <code class="language-plaintext highlighter-rouge">switch</code> 语句表达式</h2>

<p>Swift 5.9 中允许 <code class="language-plaintext highlighter-rouge">if/else</code> 和 <code class="language-plaintext highlighter-rouge">switch</code> 作为表达式，从而输出返回值。这个特性将会为你的代码提供一种优雅的写法。例如，你如果有一个 <code class="language-plaintext highlighter-rouge">let</code> 变量，其赋值语句是一个非常复杂的三元表达式：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">bullet</span> <span class="o">=</span>
    <span class="n">isRoot</span> <span class="o">&amp;&amp;</span> <span class="p">(</span><span class="n">count</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="o">!</span><span class="n">willExpand</span><span class="p">)</span> <span class="p">?</span> <span class="s">""</span>
        <span class="p">:</span> <span class="n">count</span> <span class="o">==</span> <span class="mi">0</span>    <span class="p">?</span> <span class="s">"- "</span>
        <span class="p">:</span> <span class="n">maxDepth</span> <span class="o">&lt;=</span> <span class="mi">0</span> <span class="p">?</span> <span class="s">"▹ "</span> <span class="p">:</span> <span class="s">"▿ "</span>
</code></pre></div></div>

<p>对于 <code class="language-plaintext highlighter-rouge">bullet</code> 变量的赋值条件，你可能会觉得可读性十分差。而现在，我们可以直接使用 <code class="language-plaintext highlighter-rouge">if/else</code> 表达式来改善可读性：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">bullet</span> <span class="o">=</span>
    <span class="k">if</span> <span class="n">isRoot</span> <span class="o">&amp;&amp;</span> <span class="p">(</span><span class="n">count</span> <span class="o">==</span> <span class="mi">0</span> <span class="o">||</span> <span class="o">!</span><span class="n">willExpand</span><span class="p">)</span> <span class="p">{</span> <span class="s">""</span> <span class="p">}</span>
    <span class="k">else</span> <span class="k">if</span> <span class="n">count</span> <span class="o">==</span> <span class="mi">0</span> <span class="p">{</span> <span class="s">"- "</span> <span class="p">}</span>
    <span class="k">else</span> <span class="k">if</span> <span class="n">maxDepth</span> <span class="o">&lt;=</span> <span class="mi">0</span> <span class="p">{</span> <span class="s">"▹ "</span> <span class="p">}</span>
    <span class="k">else</span> <span class="p">{</span> <span class="s">"▿ "</span> <span class="p">}</span>
</code></pre></div></div>

<p>如此修改后，我们的代码会让大家一目了然。</p>

<p>另外，在声明一个全局变量的时候，这种特性会十分友好。之前，你需要将它放在一个 closure 中，写起来是十分繁琐。例如以下代码：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">attributedName</span> <span class="o">=</span> <span class="p">{</span>
    <span class="k">if</span> <span class="k">let</span> <span class="nv">displayName</span><span class="p">,</span> <span class="o">!</span><span class="n">displayName</span><span class="o">.</span><span class="n">isEmpty</span> <span class="p">{</span>
        <span class="kt">AttributedString</span><span class="p">(</span><span class="nv">markdown</span><span class="p">:</span> <span class="n">displayName</span><span class="p">)</span>
    <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
        <span class="s">"Untitled"</span>
    <span class="p">}</span>
<span class="p">}()</span>
</code></pre></div></div>

<p>但是当我们使用这个新特性，我们可以直接去掉累赘的 closure 写法，将其简化成以下代码：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">attributedName</span> <span class="o">=</span> 
    <span class="k">if</span> <span class="k">let</span> <span class="nv">displayName</span><span class="p">,</span> <span class="o">!</span><span class="n">displayName</span><span class="o">.</span><span class="n">isEmpty</span> <span class="p">{</span>
        <span class="kt">AttributedString</span><span class="p">(</span><span class="nv">markdown</span><span class="p">:</span> <span class="n">displayName</span><span class="p">)</span>
    <span class="p">}</span> <span class="k">else</span> <span class="p">{</span>
        <span class="s">"Untitled"</span>
    <span class="p">}</span>
</code></pre></div></div>

<p>因为 <code class="language-plaintext highlighter-rouge">if/else</code>是一个带有返回值的表达式，所以这个特性可以避免之前啰嗦的写法，让代码更简洁。</p>

<h2 id="result-builder-相关工具链优化">Result Builder 相关工具链优化</h2>

<p>Result Builder （结果生成器）是驱动 SwiftUI 声明式语法的 Swift 特性之一。在前几个版本中，Swift 编译器需要花费很长的时间来确定错误，因为类型检查器搜索了大量无效路径。</p>

<p>从 Swift 5.8 开始，错误代码的类型检查速度将大幅度提升，对错误代码的错误信息现在也更加准确。</p>

<p>例如，我们来看下以下代码：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_01.png" alt="" /></p>

<p>在这个代码中，核心的问题就是 <code class="language-plaintext highlighter-rouge">NavigationLink(value: .one)</code> 中，<code class="language-plaintext highlighter-rouge">.one</code> 是一个类型错误的参数。但是在 Swift 5.7 旧版本中，会报出如图中展示的错误。Swift 5.8 对 Result Builder 诊断做了优化，不仅提高了诊断的准确性，而且也大幅度优化了时间开销。在 Swift 5.8 及之后的版本中，你将会立即查看到正确的语义诊断错误提示，例如下图：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_02.png" alt="" /></p>

<h2 id="repeat-关键字和-type-parameter-pack"><code class="language-plaintext highlighter-rouge">repeat</code> 关键字和 Type Parameter Pack</h2>

<p>在日常使用 Swift 语言中，我们会经常使用 Array ，并结合泛型特性来提供一个存储任何类型的数组。由于 Swift 具有强大的类型推断能力，使用时只需要提供其中的元素，Swift 编译器将会自动推断出来这个数组的类型。</p>

<p>但是在实际使用中，这个场景其实具有局限性。例如我们有一组数据需要处理，且它们不仅仅是单一类型的 <code class="language-plaintext highlighter-rouge">Result</code>，而是多个类型的 <code class="language-plaintext highlighter-rouge">Result</code> 入参。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">struct</span> <span class="kt">Request</span><span class="o">&lt;</span><span class="kt">Result</span><span class="o">&gt;</span> <span class="p">{</span> <span class="o">...</span> <span class="p">}</span>

<span class="kd">struct</span> <span class="kt">RequestEvaluator</span> <span class="p">{</span>
    <span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">Result</span><span class="o">&gt;</span><span class="p">(</span><span class="n">_</span> <span class="nv">request</span><span class="p">:</span> <span class="kt">Request</span><span class="o">&lt;</span><span class="kt">Result</span><span class="o">&gt;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Result</span>
<span class="p">}</span>

<span class="kd">func</span> <span class="nf">evaluate</span><span class="p">(</span><span class="n">_</span> <span class="nv">request</span><span class="p">:</span> <span class="kt">Request</span><span class="o">&lt;</span><span class="kt">Bool</span><span class="o">&gt;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Bool</span> <span class="p">{</span>
    <span class="k">return</span> <span class="kt">RequestEvaluator</span><span class="p">()</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>
<span class="p">}</span>
</code></pre></div></div>

<p>这里的 <code class="language-plaintext highlighter-rouge">evaluate</code> 方法只是一个实例，因为在实际使用过程中，我们会接收多个参数，就像下面这样：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">value</span> <span class="o">=</span> <span class="kt">RequestEvaluator</span><span class="p">()</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">(</span><span class="n">request</span><span class="p">)</span>

<span class="k">let</span> <span class="p">(</span><span class="nv">x</span><span class="p">,</span> <span class="nv">y</span><span class="p">)</span> <span class="o">=</span> <span class="kt">RequestEvaluator</span><span class="p">()</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">)</span>

<span class="k">let</span> <span class="p">(</span><span class="nv">x</span><span class="p">,</span> <span class="nv">y</span><span class="p">,</span> <span class="nv">z</span><span class="p">)</span> <span class="o">=</span> <span class="kt">RequestEvaluator</span><span class="p">()</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">,</span> <span class="n">r3</span><span class="p">)</span>
</code></pre></div></div>

<p>所以在实现的时候，我们还需要实现下面的这些多入参泛型方法：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">Result</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">Result</span><span class="p">)</span>

<span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">)</span>

<span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">)</span>

<span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">,</span> <span class="kt">R4</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:)</span><span class="o">-&gt;</span> <span class="p">(</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">,</span> <span class="kt">R4</span><span class="p">)</span>

<span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">,</span> <span class="kt">R4</span><span class="p">,</span> <span class="kt">R5</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">,</span> <span class="kt">R4</span><span class="p">,</span> <span class="kt">R5</span><span class="p">)</span>

<span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">,</span> <span class="kt">R4</span><span class="p">,</span> <span class="kt">R5</span><span class="p">,</span> <span class="kt">R6</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:</span><span class="nv">_</span><span class="p">:)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="kt">R1</span><span class="p">,</span> <span class="kt">R2</span><span class="p">,</span> <span class="kt">R3</span><span class="p">,</span> <span class="kt">R4</span><span class="p">,</span> <span class="kt">R5</span><span class="p">,</span> <span class="kt">R6</span><span class="p">)</span>
</code></pre></div></div>

<p>如此实现之后，我们就可以接收 1 - 6 个参数。但是好巧不巧，如果需要传入 7 个参数：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">results</span> <span class="o">=</span> <span class="n">evaluator</span><span class="o">.</span><span class="nf">evaluate</span><span class="p">(</span><span class="n">r1</span><span class="p">,</span> <span class="n">r2</span><span class="p">,</span> <span class="n">r3</span><span class="p">,</span> <span class="n">r4</span><span class="p">,</span> <span class="n">r5</span><span class="p">,</span> <span class="n">r6</span><span class="p">,</span> <span class="n">r7</span><span class="p">)</span>
</code></pre></div></div>

<p>对于这种尴尬的场景，在旧版本的 Swift 中就需要继续增加参数定义，从而兼容 7 个入参的场景。但是 Swift 5.9 将会简化这个流程，我们引入 <strong>Type Parameter Pack</strong> 这个概念。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">func</span> <span class="n">evaluate</span><span class="o">&lt;</span><span class="n">each</span> <span class="kt">Result</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">_</span><span class="p">:</span> <span class="k">repeat</span> <span class="kt">Request</span><span class="o">&lt;</span><span class="n">each</span> <span class="kt">Result</span><span class="o">&gt;</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="p">(</span><span class="k">repeat</span> <span class="n">each</span> <span class="kt">Result</span><span class="p">)</span>
</code></pre></div></div>

<p>我们来看引入 Type Parameter Pack 概念之后我们将如何修改这个场景。</p>

<ol>
  <li><code class="language-plaintext highlighter-rouge">&lt;each Result&gt;</code> - 这里代表我将创建一个名字叫 <code class="language-plaintext highlighter-rouge">Result</code> 的 Type Parameter Pack；</li>
  <li><code class="language-plaintext highlighter-rouge">repeat each Result</code> - 这是一个 Pack Expansion，它将 Type Parameter Pack 作为实际上表示的类型。其实这里你可以理解成<code class="language-plaintext highlighter-rouge">(each Result)...</code>，即 Type Parameter Pack 类型的不定参数。所以 <code class="language-plaintext highlighter-rouge">repeat</code>关键字更像是一个运算符（Operator）；</li>
</ol>

<p>通过这样定义，我们就可以传入不受限制个数的参数，并且可以保证每一个入参都是独立泛型类型。</p>

<p>当然这个特性，最大的受益场景就是 SwiftUI ，因为当一个 <code class="language-plaintext highlighter-rouge">View</code> 内嵌多个 <code class="language-plaintext highlighter-rouge">View</code> 的时候，SwiftUI 官方的方法就是通过泛型以及 Result Builder 进行设计的，并且最大的子 <code class="language-plaintext highlighter-rouge">View</code>有 10 个为上限的数量限制。当引入了 Type Parameter Pack 这个特性之后，限制将被突破，API 设计也更加简洁和易读。</p>

<blockquote>
  <p>Stevapple: type parameter pack 是 variadic generics（可变泛型）系列 feature 的一部分，更大的范畴上是增强 Swift 泛型系统的一部分。Variadic generics 的概念其实可以这么理解：generics 是对类型进行抽象，而 variadic generics 希望在此基础上增加对参数数量的抽象。具体的提案可以查看<a href="https://github.com/hborla/swift-evolution/blob/variadic-generics-vision/vision-documents/variadic-generics.md">这里</a>。</p>
</blockquote>

<h2 id="macro">Macro</h2>

<p>在 Swift 5.9 中，对于 Macro 的支持是重大的更新。通过 Macro ，你可以扩展语言本身的能力，消除繁琐的样板代码，并解锁 Swift 更多的表达能力。</p>

<p>我们先来看断言（assert）方法，它是用于检查一个条件是否为 <code class="language-plaintext highlighter-rouge">true</code>。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nf">assert</span><span class="p">(</span><span class="nf">max</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="n">b</span><span class="p">)</span> <span class="o">==</span> <span class="n">c</span><span class="p">)</span>
</code></pre></div></div>

<p>如果是 <code class="language-plaintext highlighter-rouge">false</code> ，断言将停止程序运行。在通常情况下，你获得到错误信息很少，因为你需要修改每一处断言调用，增加 message 信息，这样才能有效定位很多边界情况问题。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_03.png" alt="" /></p>

<p>其实 <code class="language-plaintext highlighter-rouge">XCTest</code> 也提供了一个 <code class="language-plaintext highlighter-rouge">XCAssertEqual</code> 方法，可以展示更多的错误信息。但我们实际操作后发现，即使我们知道了两边的值，也无法定位到到底是 <code class="language-plaintext highlighter-rouge">max</code> 方法的错误，还是右边 <code class="language-plaintext highlighter-rouge">c</code> 变量的问题。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_04.png" alt="" /></p>

<p>所以我们应该怎么扩展错误信息呢？在 Macro 特性推出之前，也许我们没有更好的方法。下面我们来看看如何用 Macro 特性来改善这一痛点。首先我们使用新的 hash（<code class="language-plaintext highlighter-rouge">#</code>） 的关键字来重写这段代码。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="cp">#assert(max(a, b) == c)</span>
</code></pre></div></div>

<p>或许你会觉得这个写法很熟悉，因为 Swift 中已经有很多类似的关键字，例如 <code class="language-plaintext highlighter-rouge">#file</code>、<code class="language-plaintext highlighter-rouge">#selector(...)</code> 、<code class="language-plaintext highlighter-rouge">#warning</code> 的语法。当我们断言失败后，则会使用文本符号来展示一个更加详尽的图，例如这样：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_05.png" alt="" /></p>

<p>如果我们想自己定义一个这种带有 <code class="language-plaintext highlighter-rouge">#</code> 符号的 Macro 要如何定义呢？</p>

<p>我们可以使用 <code class="language-plaintext highlighter-rouge">macro</code> 关键字来声明一个 Macro：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@freestanding</span><span class="p">(</span><span class="n">expression</span><span class="p">)</span>
<span class="kd">public</span> <span class="n">macro</span> <span class="nf">assert</span><span class="p">(</span><span class="n">_</span> <span class="nv">condition</span><span class="p">:</span> <span class="kt">Bool</span><span class="p">)</span> <span class="o">=</span> <span class="err">#</span><span class="nf">externalMacro</span><span class="p">(</span>
    <span class="nv">module</span><span class="p">:</span> <span class="s">"PowerAssertPlugin"</span><span class="p">,</span>
    <span class="nv">type</span><span class="p">:</span> <span class="s">"PowerAssertMacro"</span>
<span class="p">)</span>
</code></pre></div></div>

<p>大多数的 Macro 被定义为 External Macro，这些 External Macro 会在编译器插件的独立程序中被定义。Swift 编译器将使用 Macro 的代码传递给插件，插件产生替换后的代码，并整合回 Swift 程序中。此处，Macro 将 <code class="language-plaintext highlighter-rouge">#assert</code> 扩展成可以展示每个值的代码，其工作流程如下图：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_06.png" alt="" /></p>

<h3 id="expression-macro">Expression Macro</h3>

<p>以上介绍的 <code class="language-plaintext highlighter-rouge">#assert</code> 这个 Macro 还是一个独立表达式。我们之所以称之为“独立”，是因为它使用的是 <code class="language-plaintext highlighter-rouge">#</code> 这个关键字作为前缀调用的一种类型。这种类型是使用 <code class="language-plaintext highlighter-rouge">@freestanding(expression)</code> 进行声明的。这种表达式 Macro ，可以作为一个指定类型的 Value，放在对应的位置，编译器也会更加友好地检测它的类型。</p>

<p>在最新版本的 Foundation 中，<code class="language-plaintext highlighter-rouge">Predicate</code> API 提供了一个表达式 Macro 的极好的例子。Predicate Macro 允许你使用闭包的方式，并且会对类型安全进行校验。这种可读性很强，我们看下面的示例代码，一探便知：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">pred</span> <span class="o">=</span> <span class="err">#</span><span class="kt">Predicate</span><span class="o">&lt;</span><span class="kt">Person</span><span class="o">&gt;</span> <span class="p">{</span>
    <span class="nv">$0</span><span class="o">.</span><span class="n">favoriteColor</span> <span class="o">==</span> <span class="o">.</span><span class="n">blue</span>
<span class="p">}</span>
<span class="k">let</span> <span class="nv">blueLovers</span> <span class="o">=</span> <span class="n">people</span><span class="o">.</span><span class="nf">filter</span><span class="p">(</span><span class="n">pred</span><span class="p">)</span>
</code></pre></div></div>

<p>在 Predicate Macro 中，输入的类型是一个 Type Parameter Pack Expansion，这也就是它为什么能接受任意类型、任意数量的闭包入参。而返回值是一个 <code class="language-plaintext highlighter-rouge">Bool</code>类型的值。在使用上，我们发现它仍旧使用 <code class="language-plaintext highlighter-rouge">#</code> 符号的 Hashtag 方式，所以依旧是一个表达式 Macro。我们可以来看看它的定义代码：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@freestanding</span><span class="p">(</span><span class="n">expression</span><span class="p">)</span>
<span class="kd">public</span> <span class="n">macro</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="n">each</span> <span class="kt">Input</span><span class="o">&gt;</span><span class="p">(</span>
    <span class="n">_</span> <span class="nv">body</span><span class="p">:</span> <span class="p">(</span><span class="k">repeat</span> <span class="n">each</span> <span class="kt">Input</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Bool</span>
<span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Predicate</span><span class="o">&lt;</span><span class="k">repeat</span> <span class="n">each</span> <span class="kt">Input</span><span class="o">&gt;</span>
</code></pre></div></div>

<p>从定义上我们可以看到，这里很巧妙地用到了 Type Parameter Pack 这个特性，并且其返回值是一个 <code class="language-plaintext highlighter-rouge">Predicate</code> 类型的实例，从而可以实现多处复用的 Predicate 范式定义。</p>

<h3 id="attached-macro">Attached Macro</h3>

<p>除了这种表达式 Macro，我们还有大量的代码，需要我们对输入的参数，做出自定义的修改或者增加条件限制，显然没有输入参数的表达式 Macro 无法应对这种场景。此时，我们引入其他的 Macro，来帮助我们按照要求生成模版代码。</p>

<p>我们举个例子，例如在开发中，我们需要使用 Path 枚举类型，它可以标记一个路径是绝对路径还是相对路径。此时我们可能会遇到一个需求：<strong>从一个集合中，筛选出所有的绝对路径</strong>。例如如下代码：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">enum</span> <span class="kt">Path</span> <span class="p">{</span>
    <span class="k">case</span> <span class="nf">relative</span><span class="p">(</span><span class="kt">String</span><span class="p">)</span>
    <span class="k">case</span> <span class="nf">absolute</span><span class="p">(</span><span class="kt">String</span><span class="p">)</span>
<span class="p">}</span>

<span class="k">let</span> <span class="nv">absPaths</span> <span class="o">=</span> <span class="n">paths</span><span class="o">.</span><span class="n">filter</span> <span class="p">{</span> <span class="nv">$0</span><span class="o">.</span><span class="n">isAbsolute</span> <span class="p">}</span>

<span class="kd">extension</span> <span class="kt">Path</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">isAbsolute</span><span class="p">:</span> <span class="kt">Bool</span> <span class="p">{</span>
        <span class="k">if</span> <span class="k">case</span> <span class="o">.</span><span class="n">absolute</span> <span class="o">=</span> <span class="k">self</span> <span class="p">{</span> <span class="kc">true</span> <span class="p">}</span>
        <span class="k">else</span> <span class="p">{</span> <span class="kc">false</span> <span class="p">}</span>
    <span class="p">}</span>

    <span class="k">var</span> <span class="nv">isRelative</span><span class="p">:</span> <span class="kt">Bool</span> <span class="p">{</span>
        <span class="k">if</span> <span class="k">case</span> <span class="o">.</span><span class="n">relative</span> <span class="o">=</span> <span class="k">self</span> <span class="p">{</span> <span class="kc">true</span> <span class="p">}</span>
        <span class="k">else</span> <span class="p">{</span> <span class="kc">false</span> <span class="p">}</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>我们会发现，对于 <code class="language-plaintext highlighter-rouge">enum</code> 中的每一个 <code class="language-plaintext highlighter-rouge">case</code> 我们都需要写一个这种 <code class="language-plaintext highlighter-rouge">isCaseX</code> 的方法，从而增加一个过滤方法。此处是 <code class="language-plaintext highlighter-rouge">Path</code> 只有两种类型，但是如果在 case 更多的场景，这是一个相当繁琐的工作，而且一旦新增会带来很大的代码改动。</p>

<p>此处，我们可以引入 Attached Macro ，来生成繁琐的重复代码。使用后的代码如下：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@CaseDetection</span>
<span class="kd">enum</span> <span class="kt">Path</span> <span class="p">{</span>
    <span class="k">case</span> <span class="nf">relative</span><span class="p">(</span><span class="kt">String</span><span class="p">)</span>
    <span class="k">case</span> <span class="nf">absolute</span><span class="p">(</span><span class="kt">String</span><span class="p">)</span>
<span class="p">}</span>

<span class="k">let</span> <span class="nv">absPaths</span> <span class="o">=</span> <span class="n">paths</span><span class="o">.</span><span class="n">filter</span> <span class="p">{</span> <span class="nv">$0</span><span class="o">.</span><span class="n">isAbsolute</span> <span class="p">}</span>
</code></pre></div></div>

<p>此处的 <code class="language-plaintext highlighter-rouge">@CaseDetection</code> 是我们自定义的一个 Attached Macro，这个 Macro 的标志是使用和 Property Wrappers 特性中相同的 <code class="language-plaintext highlighter-rouge">@</code> 符号作为语法关键字，然后将其加到你需要添加的代码前方进行使用。它会根据你对于 Attached Macro 的实现，来生成代码，从而满足需求。</p>

<p>在上面这个例子中，我们的作用范围是 <code class="language-plaintext highlighter-rouge">Path</code> 这个 enum 类型的每一个 Member ，所以在使用的时候，表达是 <code class="language-plaintext highlighter-rouge">@attached(member)</code>。Attached Macro 提供 5 种作用范围给开发者使用：</p>

<table>
  <thead>
    <tr>
      <th>Attached Macro 类型</th>
      <th>作用范围</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md#member-macros"><code class="language-plaintext highlighter-rouge">@attached(member)</code></a></td>
      <td>为类型/扩展添加声明(Declaration)</td>
    </tr>
    <tr>
      <td><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md#peer-macros"><code class="language-plaintext highlighter-rouge">@attached(peer)</code></a></td>
      <td>为声明添加新的声明</td>
    </tr>
    <tr>
      <td><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md#accessor-macros"><code class="language-plaintext highlighter-rouge">@attached(accessor)</code></a></td>
      <td>为存储属性添加访问方法(<code class="language-plaintext highlighter-rouge">set</code>/<code class="language-plaintext highlighter-rouge">get</code>/<code class="language-plaintext highlighter-rouge">willSet</code>/<code class="language-plaintext highlighter-rouge">didSet</code>)</td>
    </tr>
    <tr>
      <td><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md#member-attribute-macros"><code class="language-plaintext highlighter-rouge">@attached(memberAttribute)</code></a></td>
      <td>为类型/扩展添加注解(Attributes)声明</td>
    </tr>
    <tr>
      <td><a href="https://github.com/apple/swift-evolution/blob/main/proposals/0389-attached-macros.md#conformance-macros"><code class="language-plaintext highlighter-rouge">@attached(conformance)</code></a></td>
      <td>为类型/扩展添加遵循的协议</td>
    </tr>
  </tbody>
</table>

<p>通过这些 Attached Macro 的组合使用，可以达到很好的效果。这里最重要的例子就是我们在 SwiftUI 中经常使用到的 observation 特性。</p>

<p>通过 observation 特性，我们可以观察到 class 中的 Property 的变化。想要使用这个功能，只需要让类型遵循 <code class="language-plaintext highlighter-rouge">ObservableObject</code> 协议，将每个属性标记为 <code class="language-plaintext highlighter-rouge">@Published</code> ，最后在 View 中使用 <code class="language-plaintext highlighter-rouge">ObservedObject</code> 的 Property Wrapper 即可。我们来写个示例代码：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Observation in SwiftUI</span>

<span class="kd">final</span> <span class="kd">class</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">ObservableObject</span> <span class="p">{</span>
    <span class="kd">@Published</span> <span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span>
    <span class="kd">@Published</span> <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
    <span class="kd">@Published</span> <span class="k">var</span> <span class="nv">isFavorite</span><span class="p">:</span> <span class="kt">Bool</span>
<span class="p">}</span>

<span class="kd">struct</span> <span class="kt">ContentView</span><span class="p">:</span> <span class="kt">View</span> <span class="p">{</span>
    <span class="kd">@ObservedObject</span> <span class="k">var</span> <span class="nv">person</span><span class="p">:</span> <span class="kt">Person</span>
    
    <span class="k">var</span> <span class="nv">body</span><span class="p">:</span> <span class="kd">some</span> <span class="kt">View</span> <span class="p">{</span>
        <span class="kt">Text</span><span class="p">(</span><span class="s">"Hello, </span><span class="se">\(</span><span class="n">person</span><span class="o">.</span><span class="n">name</span><span class="se">)</span><span class="s">"</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>我们会发现以上的 3 步，会有很多繁琐且复杂的工作需要我们手工处理。如果我们忘记了一步，就无法完成观察 Property 变化、自动触发 UI 刷新这样的需求。</p>

<p>当我们有了 Attached Macro 之后，我们就可以简化声明过程。例如我们有一个 <code class="language-plaintext highlighter-rouge">@Observable</code> 的 Macro ，可以完成以上操作。则我们的代码就可以精简成这样：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Observation in SwiftUI</span>

<span class="kd">@Observable</span> <span class="kd">final</span> <span class="kd">class</span> <span class="kt">Person</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
    <span class="k">var</span> <span class="nv">isFavorite</span><span class="p">:</span> <span class="kt">Bool</span>
<span class="p">}</span>

<span class="kd">struct</span> <span class="kt">ContentView</span><span class="p">:</span> <span class="kt">View</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">person</span><span class="p">:</span> <span class="kt">Person</span>
    
    <span class="k">var</span> <span class="nv">body</span><span class="p">:</span> <span class="kd">some</span> <span class="kt">View</span> <span class="p">{</span>
        <span class="kt">Text</span><span class="p">(</span><span class="s">"Hello, </span><span class="se">\(</span><span class="n">person</span><span class="o">.</span><span class="n">name</span><span class="se">)</span><span class="s">"</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>我们发现我们的代码得到了极大的精简，这得益于我们组合使用 Attached Macro 的效果。在 Macro 声明部分的代码如下：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@attached</span><span class="p">(</span><span class="n">member</span><span class="p">,</span> <span class="nv">names</span><span class="p">:</span> <span class="o">...</span><span class="p">)</span>
<span class="kd">@attached</span><span class="p">(</span><span class="n">memberAttribute</span><span class="p">)</span>
<span class="kd">@attached</span><span class="p">(</span><span class="n">conformance</span><span class="p">)</span>
<span class="kd">public</span> <span class="n">macro</span> <span class="kt">Observable</span><span class="p">()</span> <span class="o">=</span> <span class="err">#</span><span class="nf">externalMacro</span><span class="p">(</span><span class="o">...</span><span class="p">)</span><span class="o">.</span>
</code></pre></div></div>

<p>下面我们来深入探究一下每一个 Attached Macro 的作用。</p>

<p>以下是关键代码：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@Observable</span> <span class="kd">final</span> <span class="kd">class</span> <span class="kt">Person</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
    <span class="k">var</span> <span class="nv">isFavorite</span><span class="p">:</span> <span class="kt">Bool</span>
<span class="p">}</span>
</code></pre></div></div>

<p>首先，Member Macro 会引入新的属性和方法，编译器将 Macro 代码替换后将变成这样：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@Observable</span> <span class="kd">final</span> <span class="kd">class</span> <span class="kt">Person</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
    <span class="k">var</span> <span class="nv">isFavorite</span><span class="p">:</span> <span class="kt">Bool</span>

    <span class="c1">// 这里定义了一个 `ObservationRegistrar` 实例，</span>
    <span class="c1">// 用于管理观察事件的实例，当属性发生变化将通知所有 Observer</span>
    <span class="kd">internal</span> <span class="k">let</span> <span class="nv">_</span><span class="err">$</span><span class="n">observationRegistrar</span> <span class="o">=</span> <span class="kt">ObservationRegistrar</span><span class="o">&lt;</span><span class="kt">Person</span><span class="o">&gt;</span><span class="p">()</span>

    <span class="c1">// access 方法会在属性被访问时调用，通过 ObservationRegistrar 的 access</span>
    <span class="c1">// 方法，并传入被访问的属性 keyPath，来触发事件</span>
    <span class="kd">internal</span> <span class="kd">func</span> <span class="n">access</span><span class="o">&lt;</span><span class="kt">Member</span><span class="o">&gt;</span><span class="p">(</span>
        <span class="nv">keyPath</span><span class="p">:</span> <span class="kt">KeyPath</span><span class="o">&lt;</span><span class="kt">Person</span><span class="p">,</span> <span class="kt">Member</span><span class="o">&gt;</span>
    <span class="p">)</span> <span class="p">{</span>
        <span class="n">_</span><span class="err">$</span><span class="n">observationRegistrar</span><span class="o">.</span><span class="nf">access</span><span class="p">(</span><span class="k">self</span><span class="p">,</span> <span class="nv">keyPath</span><span class="p">:</span> <span class="n">keyPath</span><span class="p">)</span>
    <span class="p">}</span>

    <span class="c1">// withMutation 方法用于在修改属性时触发观察方法。在修改属性之前和之后分别触发观察事件，</span>
    <span class="c1">// 以便于观察者可以检测到属性的变化。这个方法通过 `ObservationRegistrar` 的 `withMutation`</span>
    <span class="c1">// 方法，传入被修改的属性的 keyPath 和一个闭包，这个闭包包含了对属性的修改操作</span>
    <span class="kd">internal</span> <span class="kd">func</span> <span class="n">withMutation</span><span class="o">&lt;</span><span class="kt">Member</span><span class="p">,</span> <span class="kt">T</span><span class="o">&gt;</span><span class="p">(</span>
        <span class="nv">keyPath</span><span class="p">:</span> <span class="kt">KeyPath</span><span class="o">&lt;</span><span class="kt">Person</span><span class="p">,</span> <span class="kt">Member</span><span class="o">&gt;</span><span class="p">,</span>
        <span class="n">_</span> <span class="nv">mutation</span><span class="p">:</span> <span class="p">()</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">T</span>
    <span class="p">)</span> <span class="k">rethrows</span> <span class="o">-&gt;</span> <span class="kt">T</span> <span class="p">{</span>
        <span class="k">try</span> <span class="n">_</span><span class="err">$</span><span class="n">observationRegistrar</span><span class="o">.</span><span class="nf">withMutation</span><span class="p">(</span><span class="nv">of</span><span class="p">:</span> <span class="k">self</span><span class="p">,</span> <span class="nv">keyPath</span><span class="p">:</span> <span class="n">keyPath</span><span class="p">,</span> <span class="n">mutation</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>其次，Member Attribute Macro 会为所有的属性添加 <code class="language-plaintext highlighter-rouge">@ObservationTracked</code> ，这个 Property Wrapper 会为属性添加 <code class="language-plaintext highlighter-rouge">get</code> 和 <code class="language-plaintext highlighter-rouge">set</code> 方法。</p>

<p>最后，Conformance Macro 会让 <code class="language-plaintext highlighter-rouge">Person</code> 这个 class 遵循 <code class="language-plaintext highlighter-rouge">Observable</code>协议。</p>

<p>通过这三个宏的改造，编译器将代码进行展开后，我们的真实代码类似以下：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@Observable</span> <span class="kd">final</span> <span class="kd">class</span> <span class="kt">Person</span><span class="p">:</span> <span class="kt">ObservableObject</span> <span class="p">{</span>
    <span class="kd">@ObservationTracked</span> <span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span> <span class="p">{</span> <span class="k">get</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span> <span class="k">set</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span> <span class="p">}</span>
    <span class="kd">@ObservationTracked</span> <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span> <span class="p">{</span> <span class="k">get</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span> <span class="k">set</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span> <span class="p">}</span>
    <span class="kd">@ObservationTracked</span> <span class="k">var</span> <span class="nv">isFavorite</span><span class="p">:</span> <span class="kt">Bool</span> <span class="p">{</span> <span class="k">get</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span> <span class="k">set</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span> <span class="p">}</span>

    <span class="kd">internal</span> <span class="k">let</span> <span class="nv">_</span><span class="err">$</span><span class="n">observationRegistrar</span> <span class="o">=</span> <span class="kt">ObservationRegistrar</span><span class="o">&lt;</span><span class="kt">Person</span><span class="o">&gt;</span><span class="p">()</span>
    <span class="kd">internal</span> <span class="kd">func</span> <span class="n">access</span><span class="o">&lt;</span><span class="kt">Member</span><span class="o">&gt;</span><span class="p">(</span>
        <span class="nv">keyPath</span><span class="p">:</span> <span class="kt">KeyPath</span><span class="o">&lt;</span><span class="kt">Person</span><span class="p">,</span> <span class="kt">Member</span><span class="o">&gt;</span>
    <span class="p">)</span> <span class="p">{</span>
        <span class="n">_</span><span class="err">$</span><span class="n">observationRegistrar</span><span class="o">.</span><span class="nf">access</span><span class="p">(</span><span class="k">self</span><span class="p">,</span> <span class="nv">keyPath</span><span class="p">:</span> <span class="n">keyPath</span><span class="p">)</span>
    <span class="p">}</span>
    <span class="kd">internal</span> <span class="kd">func</span> <span class="n">withMutation</span><span class="o">&lt;</span><span class="kt">Member</span><span class="p">,</span> <span class="kt">T</span><span class="o">&gt;</span><span class="p">(</span>
        <span class="nv">keyPath</span><span class="p">:</span> <span class="kt">KeyPath</span><span class="o">&lt;</span><span class="kt">Person</span><span class="p">,</span> <span class="kt">Member</span><span class="o">&gt;</span><span class="p">,</span>
        <span class="n">_</span> <span class="nv">mutation</span><span class="p">:</span> <span class="p">()</span> <span class="k">throws</span> <span class="o">-&gt;</span> <span class="kt">T</span>
    <span class="p">)</span> <span class="k">rethrows</span> <span class="o">-&gt;</span> <span class="kt">T</span> <span class="p">{</span>
        <span class="k">try</span> <span class="n">_</span><span class="err">$</span><span class="n">observationRegistrar</span><span class="o">.</span><span class="nf">withMutation</span><span class="p">(</span><span class="nv">of</span><span class="p">:</span> <span class="k">self</span><span class="p">,</span> <span class="nv">keyPath</span><span class="p">:</span> <span class="n">keyPath</span><span class="p">,</span> <span class="n">mutation</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>虽然展开后的代码十分复杂，但是绝大多数代码都被 <code class="language-plaintext highlighter-rouge">@Observable</code> Macro 封装起来了，我们只需要输入以下的简洁版本即可实现。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">@Observable</span> <span class="kd">final</span> <span class="kd">class</span> <span class="kt">Person</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">name</span><span class="p">:</span> <span class="kt">String</span>
    <span class="k">var</span> <span class="nv">age</span><span class="p">:</span> <span class="kt">Int</span>
    <span class="k">var</span> <span class="nv">isFavorite</span><span class="p">:</span> <span class="kt">Bool</span>
<span class="p">}</span>
</code></pre></div></div>

<p>当你需要对 Macro 展开，希望更好地理解程序代码时，你可以使用 Xcode 的 Expand Macro 功能对 Macro 进行源代码展开。任何在 Macro 生成的代码中出现的错误消息都会引导你去展开代码，从而快速地发现问题。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_07.png" alt="" /></p>

<p>Swift Macro 为 Swift 实现更具可读性的 API 、构建更简洁的实现语法提供了一种新的模式。Macro 可以根据我们的需求，批量生成 Swift 代码，并在程序中使用 <code class="language-plaintext highlighter-rouge">@</code> 或者 <code class="language-plaintext highlighter-rouge">#</code> 语法快速引入，简化了业务代码，也提高了可读性。</p>

<p>本文只是对 Swift Macro 进行一个初步的介绍以便于你从零到一认识。如果想学习更多，可以查看<a href="https://developer.apple.com/videos/play/wwdc2023/10166/">《Write Swift Macro》</a>这个 Session ，通过实践来编写自己的 Swift Macro。另外如果想对 Swift Macro 的设计理念有更深刻的了解，可以学习<a href="https://developer.apple.com/videos/play/wwdc2023/10167/">《Expand on Swift》</a> 这个 Session。</p>

<h2 id="swift-foundation-升级">Swift Foundation 升级</h2>

<p>Swift 这门编程语言的定位是一种可扩展的语言，其设计理念是使用清晰、简洁的代码，方便阅读和编写。其中的一些强大的特性，例如泛型、async/await 支持等等，可以支撑像 SwiftUI 或 SwiftData 这种更贴近自然描述的框架，从而允许开发者将关注点聚焦在业务上。</p>

<p>为了实现更加宽泛的可扩展性，我们需要将 Swift 适配较于 Objective-C 更多的领域，其中也包括更底层的操作系统领域，这一部分之前是由 C 或 C++ 进行编写的。</p>

<p>最近我们在 Swift 社区中，开源了 Foundation 的 Swift 重构版本，这个措施将使 Apple 以外的平台也可以享受到 Swift 带来的更加高效的性能和开发优势。但是也以为着我们需要用 Swift 对大量的 Objective-C 和 C 代码进行重构。</p>

<p>截止至 macOS Sonoma 和 iOS 17，一些基本类型已经完成了 Swift 重构版本，例如 <code class="language-plaintext highlighter-rouge">Date</code>、<code class="language-plaintext highlighter-rouge">Calendar</code>、<code class="language-plaintext highlighter-rouge">Locale</code> 和 <code class="language-plaintext highlighter-rouge">AttributedString</code>。另外 Swift 实现的 Encoder 和 Decoder 性能相较旧版本也有所提升。</p>

<p>下图是我们通过跑这些类库 Benchmark 测试用例，所得出的 Swift 重构版本的性能提升数据：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_08.png" alt="" /></p>

<p>这些性能提升除了得益于 Swift 整体工具链的性能，另外还有一个原因就是 macOS Sonoma 系统上，我们避免了语言调用时的<strong>桥接成本（Bridging Cost）</strong>，不需要再调用 Objective-C 的代码。我们从 <code class="language-plaintext highlighter-rouge">enumerateDates</code> 这个方法的调用数据统计中可以看到这个变化：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_09.png" alt="" /></p>

<h2 id="ownership--non-copyable-type">Ownership &amp; Non-copyable Type</h2>

<p>在对 Foundation 进行重构时，有时在操作系统的底层操作中，为了达到更高的性能水平，需要更细粒度的掌控。Swift 5.9 引入了“所有权”（Ownership）的概念，用来描述在你的代码中，当值在传递时，是哪段代码在“拥有”该值。</p>

<p>也许这个 Ownership 用文字描述起来有一些抽象，我们来看下示例：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">struct</span> <span class="kt">FileDescriptor</span> <span class="p">{</span>
    <span class="kd">private</span> <span class="k">var</span> <span class="nv">fd</span><span class="p">:</span> <span class="kt">CInt</span>
    
    <span class="c1">// 初始化方法，接受文件描述符作为参数</span>
    <span class="nf">init</span><span class="p">(</span><span class="nv">descriptor</span><span class="p">:</span> <span class="kt">CInt</span><span class="p">)</span> <span class="p">{</span>
        <span class="k">self</span><span class="o">.</span><span class="n">fd</span> <span class="o">=</span> <span class="n">descriptor</span>
    <span class="p">}</span>

    <span class="c1">// 写入方法，接受一个 UInt8 数组作为缓冲区，并抛出可能的错误</span>
    <span class="kd">func</span> <span class="nf">write</span><span class="p">(</span><span class="nv">buffer</span><span class="p">:</span> <span class="p">[</span><span class="kt">UInt8</span><span class="p">])</span> <span class="k">throws</span> <span class="p">{</span>
        <span class="k">let</span> <span class="nv">written</span> <span class="o">=</span> <span class="n">buffer</span><span class="o">.</span><span class="n">withUnsafeBufferPointer</span> <span class="p">{</span>
            <span class="c1">// 使用 Darwin.write 函数将缓冲区的内容写入文件描述符，并返回写入的字节数</span>
            <span class="kt">Darwin</span><span class="o">.</span><span class="nf">write</span><span class="p">(</span><span class="n">fd</span><span class="p">,</span> <span class="nv">$0</span><span class="o">.</span><span class="n">baseAddress</span><span class="p">,</span> <span class="nv">$0</span><span class="o">.</span><span class="n">count</span><span class="p">)</span>
        <span class="p">}</span>
        <span class="c1">// ...</span>
    <span class="p">}</span>
  
    <span class="c1">// 关闭方法，关闭文件描述符</span>
    <span class="kd">func</span> <span class="nf">close</span><span class="p">()</span> <span class="p">{</span>
        <span class="kt">Darwin</span><span class="o">.</span><span class="nf">close</span><span class="p">(</span><span class="n">fd</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>这是一段 FileDescriptor 的封装代码，我们可以用它更加方便的进行写文件操作。但是在使用的时候我们会经常犯一些错误，例如：你可能会在调用 <code class="language-plaintext highlighter-rouge">close()</code> 方法后，再执行 <code class="language-plaintext highlighter-rouge">write(buffer:)</code>方法。再比如：你可能会在 <code class="language-plaintext highlighter-rouge">write(buffer:)</code> 方法后，忘记调用 <code class="language-plaintext highlighter-rouge">close()</code>方法。</p>

<p>对于上面说的第二个场景，我们可以将 <code class="language-plaintext highlighter-rouge">struct</code> 修改成 <code class="language-plaintext highlighter-rouge">class</code>，通过在 <code class="language-plaintext highlighter-rouge">deinit</code> 方法中，调用 <code class="language-plaintext highlighter-rouge">close()</code> 方法，以便于在示例释放的时候，自动关闭。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">class</span> <span class="kt">FileDescriptor</span> <span class="p">{</span>
    <span class="c1">// ...</span>
    <span class="kd">deinit</span> <span class="p">{</span>
        <span class="k">self</span><span class="o">.</span><span class="nf">close</span><span class="p">(</span><span class="n">fd</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>但是这种做法也有它的缺点，例如它会造成额外的内存分配。虽然在通常情况下并不是大问题，但是在操作系统代码中某些受限的场景下是一个问题。</p>

<p>另外，<code class="language-plaintext highlighter-rouge">class</code> 构造出的示例，传递的都是引用。如果这个 <code class="language-plaintext highlighter-rouge">FileDescriptor</code> 在多个线程之间得到访问，导致竞态条件，或者持久化了这个实例导致引用计数始终大于 0 ，内存无法释放，进而引发内存泄漏。</p>

<p>再让我们重新回顾一下之前的 struct 版本。其实这个 struct 的行为也类似于引用类型。它会持有一个 <code class="language-plaintext highlighter-rouge">fd</code> 的整数，这个整数就好比引用了一个文件状态值，我们可以理解成打开了一个文件。如果我们复制了一个实例，相当于我们延长了这个文件的打开状态，如果后续代码中无意对其操作，这是不符合我们预期的。</p>

<p>Swift 的类型，无论是 <code class="language-plaintext highlighter-rouge">struct</code> 还是 <code class="language-plaintext highlighter-rouge">class</code> ，默认都是 Copyable 的。在大多数情况下，不会产生任何问题。但是有的时候，隐式复制的编译器行为，并不是我们希望的结果，尤其是在受限场景下，内存分配是我们要重点关注的问题。在 Swift 5.9 中，可以使用新的语法来强制声明禁止对类型进行隐式复制。当类型不能复制时，则可以像 <code class="language-plaintext highlighter-rouge">class</code> 一样提供一个 <code class="language-plaintext highlighter-rouge">deinit</code> 方法，在类型的值超出作用域时执行该方法。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">struct</span> <span class="kt">FileDescriptor</span><span class="p">:</span> <span class="o">~</span><span class="kt">Copyable</span> <span class="p">{</span>
    <span class="kd">private</span> <span class="k">var</span> <span class="nv">fd</span><span class="p">:</span> <span class="kt">CInt</span>
  
    <span class="nf">init</span><span class="p">(</span><span class="nv">descriptor</span><span class="p">:</span> <span class="kt">CInt</span><span class="p">)</span> <span class="p">{</span> <span class="k">self</span><span class="o">.</span><span class="n">fd</span> <span class="o">=</span> <span class="n">descriptor</span> <span class="p">}</span>

    <span class="kd">func</span> <span class="nf">write</span><span class="p">(</span><span class="nv">buffer</span><span class="p">:</span> <span class="p">[</span><span class="kt">UInt8</span><span class="p">])</span> <span class="k">throws</span> <span class="p">{</span>
        <span class="k">let</span> <span class="nv">written</span> <span class="o">=</span> <span class="n">buffer</span><span class="o">.</span><span class="n">withUnsafeBufferPointer</span> <span class="p">{</span>
            <span class="kt">Darwin</span><span class="o">.</span><span class="nf">write</span><span class="p">(</span><span class="n">fd</span><span class="p">,</span> <span class="nv">$0</span><span class="o">.</span><span class="n">baseAddress</span><span class="p">,</span> <span class="nv">$0</span><span class="o">.</span><span class="n">count</span><span class="p">)</span>
        <span class="p">}</span>
        <span class="c1">// ...</span>
    <span class="p">}</span>
  
    <span class="n">consuming</span> <span class="kd">func</span> <span class="nf">close</span><span class="p">()</span> <span class="p">{</span>
        <span class="kt">Darwin</span><span class="o">.</span><span class="nf">close</span><span class="p">(</span><span class="n">fd</span><span class="p">)</span>
    <span class="p">}</span>
  
    <span class="kd">deinit</span> <span class="p">{</span>
        <span class="kt">Darwin</span><span class="o">.</span><span class="nf">close</span><span class="p">(</span><span class="n">fd</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>像 <code class="language-plaintext highlighter-rouge">FileDescriptor</code> 这样被声明为 <code class="language-plaintext highlighter-rouge">~Copyable</code> 的类型，我们称之为 Non-copyable types 。我们通过这样声明可以解决之前提出的第一个场景。</p>

<p>这里的 <code class="language-plaintext highlighter-rouge">close</code> 操作，其实就相当于上下文已经放弃了这个实例的 Ownership，这也就是上面代码中 <code class="language-plaintext highlighter-rouge">consuming</code> 关键字的含义。当我们将方法标注为 <code class="language-plaintext highlighter-rouge">consuming</code> 后，就同时声明了 Ownership 的放弃操作，也就意味着在调用上下文中，后文将无法使用该值。</p>

<p>当我们按照这个写法，在实际业务代码中使用的时候，我们会按照这样的执行顺序进行操作：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">let</span> <span class="nv">file</span> <span class="o">=</span> <span class="kt">FileDescriptor</span><span class="p">(</span><span class="nv">fd</span><span class="p">:</span> <span class="n">descriptor</span><span class="p">)</span>
<span class="n">file</span><span class="o">.</span><span class="nf">write</span><span class="p">(</span><span class="nv">buffer</span><span class="p">:</span> <span class="n">data</span><span class="p">)</span>
<span class="n">file</span><span class="o">.</span><span class="nf">close</span><span class="p">()</span>
</code></pre></div></div>

<p>因为 <code class="language-plaintext highlighter-rouge">close</code> 操作被我们标记了是 <code class="language-plaintext highlighter-rouge">consuming</code> 方法，则它必须在最后调用，以确保在此之前上下文代码具有该实例的 Ownership。如果我们写出了错误的调用顺序，编译器将会报错，并提示我们已经放弃了 Ownership ，无法继续调用其他方法。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_10.png" alt="" /></p>

<p>Non-copyable Type 是 Swift 针对系统编程领域的一项强大的新功能，但目前仍处在早期阶段，后续版本将会不断迭代和扩展 Non-copyable Type 的功能。</p>

<h2 id="与-c-的互操作性">与 C++ 的互操作性</h2>

<h3 id="混编代码">混编代码</h3>

<p>Swift 的推广普及其中一个重要的原因就是和 Objective-C 的互操作性。从一开始，开发者就可以使用 Swift 和 Objective-C 混编的方式，在项目中逐渐将代码替换成 Swift。</p>

<p>但是我们了解到，在很多项目中，不仅用到了 Objective-C，而且还用到了 C++ 来编写核心业务，互操作接口的编写比较麻烦。通常情况下，需要手动添加 bridge 层，Swift 经过 Objective-C ，再调用 C++ ，得到返回值后，再反向传出，这是一个十分繁琐的过程。</p>

<p>Swift 5.9 引入了 Swift 与 C++ 的互操作能力特性，Swift 会将 C++ 的 API 映射成 Swift API ，从而方便调用和获得返回值。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/session_10164_11.png" alt="" /></p>

<p>C++ 是一个功能强大的语言，具有自己的类、方法、容器等诸多概念。Swift 编译器能够识别 C++ 常见的习惯用法，因此大多数类型可以直接使用。例如下面这个 <code class="language-plaintext highlighter-rouge">Person</code> 类型，定义了 C++ 类型中常见的五个成员函数：拷贝构造函数、转移（有些中文教材也叫做<strong>移动</strong>）构造函数、（两个）赋值重载运算符、析构函数。</p>

<div class="language-cpp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Person.h</span>
<span class="k">struct</span> <span class="nc">Person</span> <span class="p">{</span>
    <span class="c1">// 拷贝构造函数: 通过从另一个Person对象进行拷贝来构造新的Person对象</span>
    <span class="n">Person</span><span class="p">(</span><span class="k">const</span> <span class="n">Person</span> <span class="o">&amp;</span><span class="p">);</span>
    <span class="c1">// 转移构造函数: 通过从另一个Person对象进行移动来构造新的Person对象</span>
    <span class="n">Person</span><span class="p">(</span><span class="n">Person</span> <span class="o">&amp;&amp;</span><span class="p">);</span>
    <span class="c1">// 拷贝赋值重载运算符: 将另一个Person对象的值赋给当前对象</span>
    <span class="n">Person</span> <span class="o">&amp;</span><span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="k">const</span> <span class="n">Person</span> <span class="o">&amp;</span><span class="p">);</span>
    <span class="c1">// 转移赋值重载运算符: 通过移动另一个Person对象的值来赋给当前对象</span>
    <span class="n">Person</span> <span class="o">&amp;</span><span class="k">operator</span><span class="o">=</span><span class="p">(</span><span class="n">Person</span> <span class="o">&amp;&amp;</span><span class="p">);</span>
    <span class="c1">// 析构函数: 清理Person对象所持有的资源</span>
    <span class="o">~</span><span class="n">Person</span><span class="p">();</span>
    
    <span class="c1">// string 类型，存储人员姓名</span>
    <span class="n">std</span><span class="o">::</span><span class="n">string</span> <span class="n">name</span><span class="p">;</span>
    
    <span class="c1">// const 代表只读，用于返回人员年龄</span>
    <span class="kt">unsigned</span> <span class="n">getAge</span><span class="p">()</span> <span class="k">const</span><span class="p">;</span>
<span class="p">};</span>

<span class="c1">// 函数声明，返回一个 Person 对象的 vector 容器</span>
<span class="n">std</span><span class="o">::</span><span class="n">vector</span><span class="o">&lt;</span><span class="n">Person</span><span class="o">&gt;</span> <span class="n">everyone</span><span class="p">();</span>
</code></pre></div></div>

<p>我们通过 Swift 可以直接调用这个 C++ 的 <code class="language-plaintext highlighter-rouge">struct</code> ，也可以直接使用上面定义的 <code class="language-plaintext highlighter-rouge">vector&lt;Person&gt;</code> 。补充一句：C++ 的常规容器，例如：<code class="language-plaintext highlighter-rouge">vector</code>、<code class="language-plaintext highlighter-rouge">map</code> 等，Swift 均是可以直接访问的。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Client.swift</span>
<span class="kd">func</span> <span class="nf">greetAdults</span><span class="p">()</span> <span class="p">{</span>
    <span class="k">for</span> <span class="n">person</span> <span class="k">in</span> <span class="nf">everyone</span><span class="p">()</span><span class="o">.</span><span class="n">filter</span> <span class="p">{</span> <span class="nv">$0</span><span class="o">.</span><span class="nf">getAge</span><span class="p">()</span> <span class="o">&gt;=</span> <span class="mi">18</span> <span class="p">}</span> <span class="p">{</span>
        <span class="nf">print</span><span class="p">(</span><span class="s">"Hello, </span><span class="se">\(</span><span class="n">person</span><span class="o">.</span><span class="n">name</span><span class="se">)</span><span class="s">!"</span><span class="p">)</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>正如 <code class="language-plaintext highlighter-rouge">greetAdults()</code> 方法描述的这样，我们在 Swift 中可以直接调用 C++ 定义的类型，从而达到和 C++ 的优秀交互能力。</p>

<p>下面来说说“反向”用 C++ 调用 Swift 的场景。C++ 中使用 Swift 的代码基于与 Objective-C 相同的机制，即编译器会自动生成一个 Header 文件，我们可以在 Xcode 中找到生成后的 C++ header。然而与 Objective-C 不同的是，你不需要使用 <code class="language-plaintext highlighter-rouge">@objc</code> 这个注释对方法进行标注。C++ 大多数情况下是可以使用 Swift 完整的 API，包括属性、方法和初始化方法，无需任何桥接成本。</p>

<p>举个例子：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Geometry.swift</span>
<span class="kd">struct</span> <span class="kt">LabeledPoint</span> <span class="p">{</span>
    <span class="k">var</span> <span class="nv">x</span> <span class="o">=</span> <span class="mf">0.0</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="mf">0.0</span>
    <span class="k">var</span> <span class="nv">label</span><span class="p">:</span> <span class="kt">String</span> <span class="o">=</span> <span class="s">"origin"</span>
    <span class="k">mutating</span> <span class="kd">func</span> <span class="nf">moveBy</span><span class="p">(</span><span class="n">x</span> <span class="nv">deltaX</span><span class="p">:</span> <span class="kt">Double</span><span class="p">,</span> <span class="n">y</span> <span class="nv">deltaY</span><span class="p">:</span> <span class="kt">Double</span><span class="p">)</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
    <span class="k">var</span> <span class="nv">magnitude</span><span class="p">:</span> <span class="kt">Double</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>这是一个 Swift 定义的 <code class="language-plaintext highlighter-rouge">struct</code> ，下面我们在 C++ 文件中来使用它：</p>

<div class="language-cpp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// C++ client</span>
<span class="cp">#include</span> <span class="cpf">&lt;Geometry-Swift.h&gt;</span><span class="cp">
</span>
<span class="kt">void</span> <span class="nf">test</span><span class="p">()</span> <span class="p">{</span>
    <span class="n">Point</span> <span class="n">origin</span> <span class="o">=</span> <span class="n">Point</span><span class="p">()</span>
    <span class="n">Point</span> <span class="n">unit</span> <span class="o">=</span> <span class="n">Point</span><span class="o">::</span><span class="n">init</span><span class="p">(</span><span class="mf">1.0</span><span class="p">,</span> <span class="mf">1.0</span><span class="p">,</span> <span class="s">"unit"</span><span class="p">)</span>
    <span class="n">unit</span><span class="p">.</span><span class="n">moveBy</span><span class="p">(</span><span class="mi">2</span><span class="p">,</span> <span class="o">-</span><span class="mi">2</span><span class="p">)</span>
    <span class="n">std</span><span class="o">::</span><span class="n">cout</span> <span class="o">&lt;&lt;</span> <span class="n">unit</span><span class="p">.</span><span class="n">label</span> <span class="o">&lt;&lt;</span> <span class="s">" moved to "</span> <span class="o">&lt;&lt;</span> <span class="n">unit</span><span class="p">.</span><span class="n">magnitude</span><span class="p">()</span> <span class="o">&lt;&lt;</span> <span class="n">std</span><span class="o">::</span><span class="n">endl</span><span class="p">;</span>
<span class="p">}</span>
</code></pre></div></div>

<p>我们可以看到，在遵循 C++ 语法习惯的前提下，所有的方法名都没有发生变化，无需对 Swift 代码进行定制化修改即可完成调用。</p>

<p>Swift 的 C++ 交互让大家在业务开发中更加容易。许多 C++ 习惯用法可以直接在 Swift 中表达，通常是自动完成的，但偶尔需要一些标记（annotation）来指示所需的语义。而且，可以直接从 C++ 访问 Swift API，无需注释或更改代码，提升了开发效率，也降低了迁移成本。</p>

<blockquote>
  <p>有些地方会将 annotation 翻译成“注释”，但是校对者 stevapple 在此处建议使用标记进行翻译，因为是用作编译器来声明额外的语义操作。个人也比较采纳。</p>
</blockquote>

<p>C++ 的交互也是一个不断迭代的 feature，如果想了解更多，可以参看《Mix Swift and C++》这个 session。</p>

<h3 id="构建系统">构建系统</h3>

<p>与 C++ 的交互在语言层面上十分重要，但是我们也不能忽视构建系统的适配。因为使用 Xcode 和 Swift Package Manager 来替换 C++ 的整套构建系统，也是开发者的一个障碍。</p>

<p>这也就是为什么我们要将这个 topic 单独拿出来讨论。Swift 与 CMake 开发社区合作改进了 CMake 对 Swift 的支持。你可以将 Swift 声明为项目使用的一种语言，并将 Swift 源文件加入 target 中，从而将 Swift 代码集成到 CMake 构建中。</p>

<div class="language-cmake highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># CMake</span>

<span class="nb">project</span><span class="p">(</span>PingPong LANGUAGES CXX Swift<span class="p">)</span>

<span class="nb">add_library</span><span class="p">(</span>PingPong
            Ping.swift,
            Pong.swift,
            TableTennisUtils.cpp
<span class="p">)</span>
</code></pre></div></div>

<p>值得一提的是，你也可以在单个 Target 中混合使用 C++ 和 Swift ，CMake 将确保分别编译每个语言，并链接适用于两种语言适当的系统库和 Runtime 库。这也就意味着，你可以使用 Swift 来逐步取代跨平台的 C++ 项目。另外，Swift 社区还提供了一个包含 Swift 和混合 C++/Swift Target 的 CMake 实例存储库，其中包括使用桥接和生成的头文件，来帮助你上手。</p>

<h2 id="swift-concurrency---actor-执行器">Swift Concurrency - Actor 执行器</h2>

<p>几年前，我们引入了基于 async/await 、Structured Concurrency 以及 actors 构建的并发模型。Swift 的并发模型是一个通用抽象模型，可以适配不同的环境和库。在这个通用抽象模型中有两个主要部分，Tasks 和 Actors：</p>

<ol>
  <li>Tasks：代表可以在任意位置顺序执行的逻辑。如果有 <code class="language-plaintext highlighter-rouge">await</code> 关键字，tasks 可以被挂起，等其执行完成后继续恢复执行；</li>
  <li>Actors：是一种同步机制，提供对隔离状态的互斥访问权。从外部进入一个 actor 需要进行 <code class="language-plaintext highlighter-rouge">await</code> ，否则当前可能会将 tasks 挂起。</li>
</ol>

<p>在内部实现上，Tasks 在全局并发池（Global Concurrent Pool）上执行。全局并发池根据环境决定如何调度任务。在 Apple 平台中，Dispatch 类库为每个系统提供了针对性优化的调度策略。</p>

<p>但是和前文问题一样，我们考虑更受限的环境下，多线程调度的开销我们无法接受。在这种情况下，Swift 的并发模型则会采用单线程的协同队列（Single-threaded Cooperative Queue）进行工作。同样的代码在多种情况下都可以正常工作，因为通用抽象模型可以描述的场景很广，可以覆盖到更多 case。</p>

<p>在标准的 Swift 并发运行场景下， Actors 是通过无锁任务队列（Lock-free Queue of Tasks）来实现的，但这不是唯一的实现方式。在受限环境下，没有原子操作（Atomics），可以使用其他的并发原语（Concurrency Primitive），比如自旋锁。如果考虑单线程环境，则不需要同步机制，但 Actors 模型仍然可被通用模型覆盖到。如此你可以在单线程和多线程环境中，使用同一份代码。</p>

<p>在 Swift 5.9 中，自定义 Actor 执行器（Executors）允许实现特定的同步机制，这使 Actors 变得更加灵活。我们来看一个例子：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Custom actor executors</span>

<span class="c1">// 定义一个名为MyConnection的actor类，用于管理数据库连接</span>
<span class="kd">actor</span> <span class="kt">MyConnection</span> <span class="p">{</span>
    <span class="kd">private</span> <span class="k">var</span> <span class="nv">database</span><span class="p">:</span> <span class="kt">UnsafeMutablePointer</span><span class="o">&lt;</span><span class="n">sqlite3</span><span class="o">&gt;</span>
  
    <span class="c1">// 初始化方法，接收一个文件名作为参数，并抛出异常</span>
    <span class="nf">init</span><span class="p">(</span><span class="nv">filename</span><span class="p">:</span> <span class="kt">String</span><span class="p">)</span> <span class="k">throws</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
  
    <span class="c1">// 用于清理旧条目的方法</span>
    <span class="kd">func</span> <span class="nf">pruneOldEntries</span><span class="p">()</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
  
    <span class="c1">// 根据给定的名称和类型，从数据库中获取一个条目</span>
    <span class="kd">func</span> <span class="n">fetchEntry</span><span class="o">&lt;</span><span class="kt">Entry</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">named</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="nv">type</span><span class="p">:</span> <span class="kt">Entry</span><span class="o">.</span><span class="k">Type</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Entry</span><span class="p">?</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
<span class="p">}</span>

<span class="c1">// 在外部调用时使用"await"来暂停当前任务，等待pruneOldEntries方法完成</span>
<span class="k">await</span> <span class="n">connection</span><span class="o">.</span><span class="nf">pruneOldEntries</span><span class="p">()</span>
</code></pre></div></div>

<p>这是一个管理数据库连接的 Actor 例子。Swift 确保代码对 Actor 互斥访问，所以不会出现对数据库的并发访问。但是如果你需要对同步访问进行控制要如何做呢？例如，当你连接数据库的时候，你想在某个队列上执行，而不是一个未知的、未与其他线程共享的队列。在 Swift 5.9 中，可以自定义 actor 执行器，可以这样实现：</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="kd">actor</span> <span class="kt">MyConnection</span> <span class="p">{</span>
  <span class="kd">private</span> <span class="k">var</span> <span class="nv">database</span><span class="p">:</span> <span class="kt">UnsafeMutablePointer</span><span class="o">&lt;</span><span class="n">sqlite3</span><span class="o">&gt;</span>

  <span class="c1">// 执行方法的队列</span>
  <span class="kd">private</span> <span class="k">let</span> <span class="nv">queue</span><span class="p">:</span> <span class="kt">DispatchSerialQueue</span>

  <span class="c1">// 这里自定义 actor 的执行器，nonisolated 定义为它是一个非孤立方法，即不需要在外部使用 await 关键字</span>
  <span class="kd">nonisolated</span> <span class="k">var</span> <span class="nv">unownedExecutor</span><span class="p">:</span> <span class="kt">UnownedSerialExecutor</span> <span class="p">{</span> <span class="n">queue</span><span class="o">.</span><span class="nf">asUnownedSerialExecutor</span><span class="p">()</span> <span class="p">}</span>

  <span class="nf">init</span><span class="p">(</span><span class="nv">filename</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="nv">queue</span><span class="p">:</span> <span class="kt">DispatchSerialQueue</span><span class="p">)</span> <span class="k">throws</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
  
  <span class="kd">func</span> <span class="nf">pruneOldEntries</span><span class="p">()</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
  <span class="kd">func</span> <span class="n">fetchEntry</span><span class="o">&lt;</span><span class="kt">Entry</span><span class="o">&gt;</span><span class="p">(</span><span class="nv">named</span><span class="p">:</span> <span class="kt">String</span><span class="p">,</span> <span class="nv">type</span><span class="p">:</span> <span class="kt">Entry</span><span class="o">.</span><span class="k">Type</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Entry</span><span class="p">?</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
<span class="p">}</span>

<span class="k">await</span> <span class="n">connection</span><span class="o">.</span><span class="nf">pruneOldEntries</span><span class="p">()</span>
</code></pre></div></div>

<p>上述代码中，我们为 actor 添加了一个串行调度队列，并且提供了一个 <code class="language-plaintext highlighter-rouge">unownedExecutor</code> 的实现，用于生成与该队列关联的执行器。通过这个改变，所有 actor 实例的同步方法将通过这个队列来执行。</p>

<p>当你在外部调用 <code class="language-plaintext highlighter-rouge">await connection.pruneOldEntries()</code> 时，其实现在真正的行为是在上方的队列里调用了 <code class="language-plaintext highlighter-rouge">dispatchQueue.async</code> 。有了这个自定义执行器后，我们可以全方位控制 Actor 的方法调度，甚至可以与未使用 Actor 的方法混用并调度他们的执行顺序。</p>

<p>我们可以通过调度队列对 actor 进行同步调度，是因为调度队列遵循了新的 <code class="language-plaintext highlighter-rouge">SerialExecutor</code> 协议。开发者可以通过实现一个符合该协议的类，从而定义自己的调度机制。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// Executor protocols</span>

<span class="kd">protocol</span> <span class="kt">Executor</span><span class="p">:</span> <span class="kt">AnyObject</span><span class="p">,</span> <span class="kt">Sendable</span> <span class="p">{</span>
    <span class="c1">// 方法 1 </span>
    <span class="kd">func</span> <span class="nf">enqueue</span><span class="p">(</span><span class="n">_</span> <span class="nv">job</span><span class="p">:</span> <span class="n">consuming</span> <span class="kt">ExecutorJob</span><span class="p">)</span>
<span class="p">}</span>

<span class="kd">protocol</span> <span class="kt">SerialExecutor</span><span class="p">:</span> <span class="kt">Executor</span> <span class="p">{</span>
    <span class="c1">// 方法 2：</span>
    <span class="kd">func</span> <span class="nf">asUnownedSerialExecutor</span><span class="p">()</span> <span class="o">-&gt;</span> <span class="kt">UnownedSerialExecutor</span>
    <span class="c1">// 方法 3：</span>
    <span class="kd">func</span> <span class="nf">isSameExclusiveExecutionContext</span><span class="p">(</span><span class="n">other</span> <span class="nv">executor</span><span class="p">:</span> <span class="k">Self</span><span class="p">)</span> <span class="o">-&gt;</span> <span class="kt">Bool</span>
<span class="p">}</span>

<span class="kd">extension</span> <span class="kt">DispatchSerialQueue</span><span class="p">:</span> <span class="kt">SerialExecutor</span> <span class="p">{</span> <span class="err">…</span> <span class="p">}</span>
</code></pre></div></div>

<p>在这个协议中包括了一些核心操作：</p>

<ol>
  <li>检查代码是否已经在执行器上下文中执行：如上代码中的方法 3 <code class="language-plaintext highlighter-rouge">isSameExclusiveExecutionContext(other:)</code>。例如：你可以实现是否在主线程上执行。</li>
  <li>可以获取这个 Executor 对应的执行器实例，并访问它：如上代码中的方法 2 <code class="language-plaintext highlighter-rouge">asUnownedSerialExecutor()</code>。</li>
  <li>将某个 Job 的所有权给到这个执行器：如上述代码中的方法 1 <code class="language-plaintext highlighter-rouge">enqueue(_:)</code>。</li>
</ol>

<p>Job 是需要在执行器上同步完成异步任务，这样的一个概念。从运行表现上来说，还是列举上面数据库连接的例子，<code class="language-plaintext highlighter-rouge">enqueue</code>方法将会在我们声明的队列上，调用 <code class="language-plaintext highlighter-rouge">dispatchQueue.async</code> 方法。</p>

<p>Swift 并发编程目前已经有了几年的经验，Tasks 和 Actor 这套模型也覆盖了诸多并发场景。从 iPhone 到 Apple Watch ，再到 Server ，其已适应不同的执行环境。这是一套复杂却又实用的系统，如果你希望了解更多，可以查看<a href="https://developer.apple.com/videos/play/wwdc2021/10254/">《Behind the Scenes》</a>和<a href="https://developer.apple.com/videos/play/wwdc2023/10170/">《Beyond the basics of Structured Concurrency》</a>这两个 Session。</p>

<h2 id="foundationdb">FoundationDB</h2>

<p>最后我们介绍一点额外的东西，FoundationDB。这是一个分布式数据库，用于在普通硬件上运行的可扩展数据库解决方案。目前已经支持 macOS 、Linux 和 Windows。</p>

<p>FoundationDB 是一个开源项目，代码量很大，且使用 C++ 编写。这些代码是强异步的，具有自己的分布式 Actor 和 Runtime 实现。FoundationDB 项目希望对其代码进行现代化改造，并且认为 Swift 在性能、安全性和代码可读性上与其需求十分匹配。但是完全使用 Swift 重构是一个非常冒险的任务，所以在最新版代码中，开发人员利用 Swift 与 C++ 的交互新特性，进行部分的重构。</p>

<p>首先我们来看一下 FoundationDB 部分的 Actor 代码片段 C++ 实现：</p>

<div class="language-cpp highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// FoundationDB的“master data” actor的C++实现</span>

<span class="c1">// 异步函数，用于获取版本号</span>
<span class="n">ACTOR</span> <span class="n">Future</span><span class="o">&lt;</span><span class="n">Void</span><span class="o">&gt;</span> <span class="n">getVersion</span><span class="p">(</span><span class="n">Reference</span><span class="o">&lt;</span><span class="n">MasterData</span><span class="o">&gt;</span> <span class="n">self</span><span class="p">,</span> <span class="n">GetCommitVersionRequest</span> <span class="n">req</span><span class="p">)</span> <span class="p">{</span>
    <span class="c1">// 查找请求代理的迭代器</span>
    <span class="n">state</span> <span class="n">std</span><span class="o">::</span><span class="n">map</span><span class="o">&lt;</span><span class="n">UID</span><span class="p">,</span> <span class="n">CommitProxyVersionReplies</span><span class="o">&gt;::</span><span class="n">iterator</span> <span class="n">proxyItr</span> <span class="o">=</span> <span class="n">self</span><span class="o">-&gt;</span><span class="n">lastCommitProxyVersionReplies</span><span class="p">.</span><span class="n">find</span><span class="p">(</span><span class="n">req</span><span class="p">.</span><span class="n">requestingProxy</span><span class="p">);</span>
    <span class="o">++</span><span class="n">self</span><span class="o">-&gt;</span><span class="n">getCommitVersionRequests</span><span class="p">;</span>

    <span class="c1">// 如果在映射中找不到代理的迭代器，则发送一个“Never”的响应并返回</span>
    <span class="k">if</span> <span class="p">(</span><span class="n">proxyItr</span> <span class="o">==</span> <span class="n">self</span><span class="o">-&gt;</span><span class="n">lastCommitProxyVersionReplies</span><span class="p">.</span><span class="n">end</span><span class="p">())</span> <span class="p">{</span>
        <span class="n">req</span><span class="p">.</span><span class="n">reply</span><span class="p">.</span><span class="n">send</span><span class="p">(</span><span class="n">Never</span><span class="p">());</span>
        <span class="k">return</span> <span class="n">Void</span><span class="p">();</span>
    <span class="p">}</span>

    <span class="c1">// 等待直到最新的请求编号至少达到 req.requestNum - 1</span>
    <span class="n">wait</span><span class="p">(</span><span class="n">proxyItr</span><span class="o">-&gt;</span><span class="n">second</span><span class="p">.</span><span class="n">latestRequestNum</span><span class="p">.</span><span class="n">whenAtLeast</span><span class="p">(</span><span class="n">req</span><span class="p">.</span><span class="n">requestNum</span> <span class="o">-</span> <span class="mi">1</span><span class="p">));</span>

    <span class="c1">// 在回复的映射中查找与请求编号对应的回复</span>
    <span class="k">auto</span> <span class="n">itr</span> <span class="o">=</span> <span class="n">proxyItr</span><span class="o">-&gt;</span><span class="n">second</span><span class="p">.</span><span class="n">replies</span><span class="p">.</span><span class="n">find</span><span class="p">(</span><span class="n">req</span><span class="p">.</span><span class="n">requestNum</span><span class="p">);</span>
    <span class="k">if</span> <span class="p">(</span><span class="n">itr</span> <span class="o">!=</span> <span class="n">proxyItr</span><span class="o">-&gt;</span><span class="n">second</span><span class="p">.</span><span class="n">replies</span><span class="p">.</span><span class="n">end</span><span class="p">())</span> <span class="p">{</span>
        <span class="c1">// 如果找到回复，则将其作为响应发送并返回</span>
        <span class="n">req</span><span class="p">.</span><span class="n">reply</span><span class="p">.</span><span class="n">send</span><span class="p">(</span><span class="n">itr</span><span class="o">-&gt;</span><span class="n">second</span><span class="p">);</span>
        <span class="k">return</span> <span class="n">Void</span><span class="p">();</span>
    <span class="p">}</span>

    <span class="c1">// ...</span>
<span class="p">}</span>
</code></pre></div></div>

<p>这段代码有很多内容，你并不需要了解这段 C++ 代码。其中，我只想指出一个关键的地方：因为 C++ 没有 async/await ，所以 FoundationDB 使用了类似于预处理器（Preprocessor）的方式进行模拟实现。</p>

<p>通过对应的编号进行筛选，从而显式实现了消息匹配，从而将正确的结果返回。最后，FoundationDB 有自己的引用计数智能指针来帮助自动管理内存。上述 C++ 代码描述的就是这样的一个过程。</p>

<p>但如果我们使用 Swift ，这个方法就可以直接使用异步函数的特性，使用 <code class="language-plaintext highlighter-rouge">await</code> 来表示对于请求的匹配，就节省了上述大量的代码逻辑。</p>

<div class="language-swift highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1">// FoundationDB的“master data” actor的Swift实现</span>

<span class="c1">// 异步函数，用于获取版本号</span>
<span class="kd">func</span> <span class="nf">getVersion</span><span class="p">(</span>
    <span class="nv">myself</span><span class="p">:</span> <span class="kt">MasterData</span><span class="p">,</span> <span class="nv">req</span><span class="p">:</span> <span class="kt">GetCommitVersionRequest</span>
<span class="p">)</span> <span class="k">async</span> <span class="o">-&gt;</span> <span class="kt">GetCommitVersionReply</span><span class="p">?</span> <span class="p">{</span>
    <span class="c1">// 增加getCommitVersionRequests计数</span>
    <span class="n">myself</span><span class="o">.</span><span class="n">getCommitVersionRequests</span> <span class="o">+=</span> <span class="mi">1</span>

    <span class="c1">// 检查是否存在请求代理的最后版本回复</span>
    <span class="k">guard</span> <span class="k">let</span> <span class="nv">lastVersionReplies</span> <span class="o">=</span> <span class="n">lastCommitProxyVersionReplies</span><span class="p">[</span><span class="n">req</span><span class="o">.</span><span class="n">requestingProxy</span><span class="p">]</span> <span class="k">else</span> <span class="p">{</span>
        <span class="k">return</span> <span class="kc">nil</span>
    <span class="p">}</span>

    <span class="c1">// ...</span>
    <span class="c1">// 等待直到latestRequestNum至少达到req.requestNum - 1</span>
    <span class="k">var</span> <span class="nv">latestRequestNum</span> <span class="o">=</span> <span class="k">try</span> <span class="k">await</span> <span class="n">lastVersionReplies</span><span class="o">.</span><span class="n">latestRequestNum</span>
        <span class="o">.</span><span class="nf">atLeast</span><span class="p">(</span><span class="kt">VersionMetricHandle</span><span class="o">.</span><span class="kt">ValueType</span><span class="p">(</span><span class="n">req</span><span class="o">.</span><span class="n">requestNum</span> <span class="o">-</span> <span class="kt">UInt64</span><span class="p">(</span><span class="mi">1</span><span class="p">)))</span>

    <span class="c1">// 如果存在请求编号对应的最后回复，则返回该回复</span>
    <span class="k">if</span> <span class="k">let</span> <span class="nv">lastReply</span> <span class="o">=</span> <span class="n">lastVersionReplies</span><span class="o">.</span><span class="n">replies</span><span class="p">[</span><span class="n">req</span><span class="o">.</span><span class="n">requestNum</span><span class="p">]</span> <span class="p">{</span>
        <span class="k">return</span> <span class="n">lastReply</span>
    <span class="p">}</span>
<span class="p">}</span>
</code></pre></div></div>

<p>是不是可读性提高了不少？</p>

<p>另外，我们在这里使用了很多 C++ 类型，C++ 中的 MasterData 类型使用了引用计数智能指针。通过在 C++ 中对类型进行标注，Swift 编译器可以像任何其他类一样使用该类型，自动管理引用计数。</p>

<p>从这个例子中，我们获取到的经验是，我们可以在需要的时候，使用 Swift 的优势来改写逻辑，与现有的 C++ 代码进行接口互调操作，实现渐进式的代码替换，最终也可以推进项目 Swift 化的进程。</p>

<h2 id="总结">总结</h2>

<p>这个 Session 中我们讨论了很多内容，不乏 Swift 的一些新的语法特性和 Swift Macros。这些功能可以实现更加灵活和健壮的 API，帮助你更好地编写高质量代码。</p>

<p>另外，我们也大篇幅的讨论了在受限环境下使用 Swift 的优势，以及 Swift 如何灵活的适配多种平台设备、语言，这些也为我们在编写代码中，获得更多的思考。</p>

<p>这些特性的出现和设计，都是通过 Swift 社区中从 idea 、公开讨论、结果反馈等等流程中孕育而生的。感谢各位开发者的支持，让 Swift 5.9 这门编程语言更加健壮。</p>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="iOS" /><category term="Swift" /><category term="Apple" /><summary type="html"><![CDATA[摘要：这个 Session 涉及了 Swift 的新语法特性和 Swift Macro 的话题，这些功能对于编写更加灵活和健壮的 API 以及高质量代码起到了很大的帮助。此外，也深入探讨了在受限环境下使用 Swift 的优势，并讨论了 Swift 在适配多种平台设备和语言方面的灵活性。 本文基于 Session 10164 梳理。 审核： stevapple：学生，Swift/Vapor 社区贡献者 kemchenj：老司机技术核心成员 / 开源爱好者 / 最近在做 3D 重建相关的开发工作 今年是 Swift 的一次重大更新，这个 Session 将和大家一起聊聊 Swift 语言今年的一些改进、简洁的语法糖以及一些强大的新 API 的使用。一年前，Swift 项目的核心团队宣布了成立 Language Steering Group ，主要负责监督 Swift 语言和标准库的修改。从这之后，Language Steering Group 已经审核了 40 多个新的提案，这些会覆盖到我们今天所要讨论的几个。 有很多社区提案都有相同的思路和看法，所以我们会将这些类似的提案进行合并。而在这之中，Swift Macro（在 C 的中文教材中，一般称作宏，下文继续使用 Macro 进行代替）是提及最多的一个提案，所以我们后文也会具体讨论 Swift 5.9 中关于 Swift Macro 的新特性。 当然，语言的演进只是 Swift 社区工作的一部分，一门成功的语言需要的远不止这些，它还需要配合优秀的工具链、多平台的强大支持以及丰富的文档。为了全方位的监控进展，核心团队也正在组建一个 Ecosystem Steering Group ，这个新的团队也在 swift.org 的博客中有所提及，我们可以一起期待一下这个团队的进一步公告。 现在我们进入正题，来讨论一下今年 Swift 语言的更新。 if/else 和 switch 语句表达式 Swift 5.9 中允许 if/else 和 switch 作为表达式，从而输出返回值。这个特性将会为你的代码提供一种优雅的写法。例如，你如果有一个 let 变量，其赋值语句是一个非常复杂的三元表达式： let bullet = isRoot &amp;&amp; (count == 0 || !willExpand) ? "" : count == 0 ? "- " : maxDepth &lt;= 0 ? "▹ " : "▿ " 对于 bullet 变量的赋值条件，你可能会觉得可读性十分差。而现在，我们可以直接使用 if/else 表达式来改善可读性： let bullet = if isRoot &amp;&amp; (count == 0 || !willExpand) { "" } else if count == 0 { "- " } else if maxDepth &lt;= 0 { "▹ " } else { "▿ " } 如此修改后，我们的代码会让大家一目了然。 另外，在声明一个全局变量的时候，这种特性会十分友好。之前，你需要将它放在一个 closure 中，写起来是十分繁琐。例如以下代码： let attributedName = { if let displayName, !displayName.isEmpty { AttributedString(markdown: displayName) } else { "Untitled" } }() 但是当我们使用这个新特性，我们可以直接去掉累赘的 closure 写法，将其简化成以下代码： let attributedName = if let displayName, !displayName.isEmpty { AttributedString(markdown: displayName) } else { "Untitled" } 因为 if/else是一个带有返回值的表达式，所以这个特性可以避免之前啰嗦的写法，让代码更简洁。 Result Builder 相关工具链优化 Result Builder （结果生成器）是驱动 SwiftUI 声明式语法的 Swift 特性之一。在前几个版本中，Swift 编译器需要花费很长的时间来确定错误，因为类型检查器搜索了大量无效路径。 从 Swift 5.8 开始，错误代码的类型检查速度将大幅度提升，对错误代码的错误信息现在也更加准确。 例如，我们来看下以下代码： 在这个代码中，核心的问题就是 NavigationLink(value: .one) 中，.one 是一个类型错误的参数。但是在 Swift 5.7 旧版本中，会报出如图中展示的错误。Swift 5.8 对 Result Builder 诊断做了优化，不仅提高了诊断的准确性，而且也大幅度优化了时间开销。在 Swift 5.8 及之后的版本中，你将会立即查看到正确的语义诊断错误提示，例如下图： repeat 关键字和 Type Parameter Pack 在日常使用 Swift 语言中，我们会经常使用 Array ，并结合泛型特性来提供一个存储任何类型的数组。由于 Swift 具有强大的类型推断能力，使用时只需要提供其中的元素，Swift 编译器将会自动推断出来这个数组的类型。 但是在实际使用中，这个场景其实具有局限性。例如我们有一组数据需要处理，且它们不仅仅是单一类型的 Result，而是多个类型的 Result 入参。 struct Request&lt;Result&gt; { ... } struct RequestEvaluator { func evaluate&lt;Result&gt;(_ request: Request&lt;Result&gt;) -&gt; Result } func evaluate(_ request: Request&lt;Bool&gt;) -&gt; Bool { return RequestEvaluator().evaluate(request) } 这里的 evaluate 方法只是一个实例，因为在实际使用过程中，我们会接收多个参数，就像下面这样： let value = RequestEvaluator().evaluate(request) let (x, y) = RequestEvaluator().evaluate(r1, r2) let (x, y, z) = RequestEvaluator().evaluate(r1, r2, r3) 所以在实现的时候，我们还需要实现下面的这些多入参泛型方法： func evaluate&lt;Result&gt;(_:) -&gt; (Result) func evaluate&lt;R1, R2&gt;(_:_:) -&gt; (R1, R2) func evaluate&lt;R1, R2, R3&gt;(_:_:_:) -&gt; (R1, R2, R3) func evaluate&lt;R1, R2, R3, R4&gt;(_:_:_:_:)-&gt; (R1, R2, R3, R4) func evaluate&lt;R1, R2, R3, R4, R5&gt;(_:_:_:_:_:) -&gt; (R1, R2, R3, R4, R5) func evaluate&lt;R1, R2, R3, R4, R5, R6&gt;(_:_:_:_:_:_:) -&gt; (R1, R2, R3, R4, R5, R6) 如此实现之后，我们就可以接收 1 - 6 个参数。但是好巧不巧，如果需要传入 7 个参数： let results = evaluator.evaluate(r1, r2, r3, r4, r5, r6, r7) 对于这种尴尬的场景，在旧版本的 Swift 中就需要继续增加参数定义，从而兼容 7 个入参的场景。但是 Swift 5.9 将会简化这个流程，我们引入 Type Parameter Pack 这个概念。 func evaluate&lt;each Result&gt;(_: repeat Request&lt;each Result&gt;) -&gt; (repeat each Result) 我们来看引入 Type Parameter Pack 概念之后我们将如何修改这个场景。 &lt;each Result&gt; - 这里代表我将创建一个名字叫 Result 的 Type Parameter Pack； repeat each Result - 这是一个 Pack Expansion，它将 Type Parameter Pack 作为实际上表示的类型。其实这里你可以理解成(each Result)...，即 Type Parameter Pack 类型的不定参数。所以 repeat关键字更像是一个运算符（Operator）； 通过这样定义，我们就可以传入不受限制个数的参数，并且可以保证每一个入参都是独立泛型类型。 当然这个特性，最大的受益场景就是 SwiftUI ，因为当一个 View 内嵌多个 View 的时候，SwiftUI 官方的方法就是通过泛型以及 Result Builder 进行设计的，并且最大的子 View有 10 个为上限的数量限制。当引入了 Type Parameter Pack 这个特性之后，限制将被突破，API 设计也更加简洁和易读。 Stevapple: type parameter pack 是 variadic generics（可变泛型）系列 feature 的一部分，更大的范畴上是增强 Swift 泛型系统的一部分。Variadic generics 的概念其实可以这么理解：generics 是对类型进行抽象，而 variadic generics 希望在此基础上增加对参数数量的抽象。具体的提案可以查看这里。 Macro 在 Swift 5.9 中，对于 Macro 的支持是重大的更新。通过 Macro ，你可以扩展语言本身的能力，消除繁琐的样板代码，并解锁 Swift 更多的表达能力。 我们先来看断言（assert）方法，它是用于检查一个条件是否为 true。 assert(max(a, b) == c) 如果是 false ，断言将停止程序运行。在通常情况下，你获得到错误信息很少，因为你需要修改每一处断言调用，增加 message 信息，这样才能有效定位很多边界情况问题。 其实 XCTest 也提供了一个 XCAssertEqual 方法，可以展示更多的错误信息。但我们实际操作后发现，即使我们知道了两边的值，也无法定位到到底是 max 方法的错误，还是右边 c 变量的问题。 所以我们应该怎么扩展错误信息呢？在 Macro 特性推出之前，也许我们没有更好的方法。下面我们来看看如何用 Macro 特性来改善这一痛点。首先我们使用新的 hash（#） 的关键字来重写这段代码。 #assert(max(a, b) == c) 或许你会觉得这个写法很熟悉，因为 Swift 中已经有很多类似的关键字，例如 #file、#selector(...) 、#warning 的语法。当我们断言失败后，则会使用文本符号来展示一个更加详尽的图，例如这样： 如果我们想自己定义一个这种带有 # 符号的 Macro 要如何定义呢？ 我们可以使用 macro 关键字来声明一个 Macro： @freestanding(expression) public macro assert(_ condition: Bool) = #externalMacro( module: "PowerAssertPlugin", type: "PowerAssertMacro" ) 大多数的 Macro 被定义为 External Macro，这些 External Macro 会在编译器插件的独立程序中被定义。Swift 编译器将使用 Macro 的代码传递给插件，插件产生替换后的代码，并整合回 Swift 程序中。此处，Macro 将 #assert 扩展成可以展示每个值的代码，其工作流程如下图： Expression Macro 以上介绍的 #assert 这个 Macro 还是一个独立表达式。我们之所以称之为“独立”，是因为它使用的是 # 这个关键字作为前缀调用的一种类型。这种类型是使用 @freestanding(expression) 进行声明的。这种表达式 Macro ，可以作为一个指定类型的 Value，放在对应的位置，编译器也会更加友好地检测它的类型。 在最新版本的 Foundation 中，Predicate API 提供了一个表达式 Macro 的极好的例子。Predicate Macro 允许你使用闭包的方式，并且会对类型安全进行校验。这种可读性很强，我们看下面的示例代码，一探便知： let pred = #Predicate&lt;Person&gt; { $0.favoriteColor == .blue } let blueLovers = people.filter(pred) 在 Predicate Macro 中，输入的类型是一个 Type Parameter Pack Expansion，这也就是它为什么能接受任意类型、任意数量的闭包入参。而返回值是一个 Bool类型的值。在使用上，我们发现它仍旧使用 # 符号的 Hashtag 方式，所以依旧是一个表达式 Macro。我们可以来看看它的定义代码： @freestanding(expression) public macro Predicate&lt;each Input&gt;( _ body: (repeat each Input) -&gt; Bool ) -&gt; Predicate&lt;repeat each Input&gt; 从定义上我们可以看到，这里很巧妙地用到了 Type Parameter Pack 这个特性，并且其返回值是一个 Predicate 类型的实例，从而可以实现多处复用的 Predicate 范式定义。 Attached Macro 除了这种表达式 Macro，我们还有大量的代码，需要我们对输入的参数，做出自定义的修改或者增加条件限制，显然没有输入参数的表达式 Macro 无法应对这种场景。此时，我们引入其他的 Macro，来帮助我们按照要求生成模版代码。 我们举个例子，例如在开发中，我们需要使用 Path 枚举类型，它可以标记一个路径是绝对路径还是相对路径。此时我们可能会遇到一个需求：从一个集合中，筛选出所有的绝对路径。例如如下代码： enum Path { case relative(String) case absolute(String) } let absPaths = paths.filter { $0.isAbsolute } extension Path { var isAbsolute: Bool { if case .absolute = self { true } else { false } } var isRelative: Bool { if case .relative = self { true } else { false } } } 我们会发现，对于 enum 中的每一个 case 我们都需要写一个这种 isCaseX 的方法，从而增加一个过滤方法。此处是 Path 只有两种类型，但是如果在 case 更多的场景，这是一个相当繁琐的工作，而且一旦新增会带来很大的代码改动。 此处，我们可以引入 Attached Macro ，来生成繁琐的重复代码。使用后的代码如下： @CaseDetection enum Path { case relative(String) case absolute(String) } let absPaths = paths.filter { $0.isAbsolute } 此处的 @CaseDetection 是我们自定义的一个 Attached Macro，这个 Macro 的标志是使用和 Property Wrappers 特性中相同的 @ 符号作为语法关键字，然后将其加到你需要添加的代码前方进行使用。它会根据你对于 Attached Macro 的实现，来生成代码，从而满足需求。 在上面这个例子中，我们的作用范围是 Path 这个 enum 类型的每一个 Member ，所以在使用的时候，表达是 @attached(member)。Attached Macro 提供 5 种作用范围给开发者使用： Attached Macro 类型 作用范围 @attached(member) 为类型/扩展添加声明(Declaration) @attached(peer) 为声明添加新的声明 @attached(accessor) 为存储属性添加访问方法(set/get/willSet/didSet) @attached(memberAttribute) 为类型/扩展添加注解(Attributes)声明 @attached(conformance) 为类型/扩展添加遵循的协议 通过这些 Attached Macro 的组合使用，可以达到很好的效果。这里最重要的例子就是我们在 SwiftUI 中经常使用到的 observation 特性。 通过 observation 特性，我们可以观察到 class 中的 Property 的变化。想要使用这个功能，只需要让类型遵循 ObservableObject 协议，将每个属性标记为 @Published ，最后在 View 中使用 ObservedObject 的 Property Wrapper 即可。我们来写个示例代码： // Observation in SwiftUI final class Person: ObservableObject { @Published var name: String @Published var age: Int @Published var isFavorite: Bool } struct ContentView: View { @ObservedObject var person: Person var body: some View { Text("Hello, \(person.name)") } } 我们会发现以上的 3 步，会有很多繁琐且复杂的工作需要我们手工处理。如果我们忘记了一步，就无法完成观察 Property 变化、自动触发 UI 刷新这样的需求。 当我们有了 Attached Macro 之后，我们就可以简化声明过程。例如我们有一个 @Observable 的 Macro ，可以完成以上操作。则我们的代码就可以精简成这样： // Observation in SwiftUI @Observable final class Person { var name: String var age: Int var isFavorite: Bool } struct ContentView: View { var person: Person var body: some View { Text("Hello, \(person.name)") } } 我们发现我们的代码得到了极大的精简，这得益于我们组合使用 Attached Macro 的效果。在 Macro 声明部分的代码如下： @attached(member, names: ...) @attached(memberAttribute) @attached(conformance) public macro Observable() = #externalMacro(...). 下面我们来深入探究一下每一个 Attached Macro 的作用。 以下是关键代码： @Observable final class Person { var name: String var age: Int var isFavorite: Bool } 首先，Member Macro 会引入新的属性和方法，编译器将 Macro 代码替换后将变成这样： @Observable final class Person { var name: String var age: Int var isFavorite: Bool // 这里定义了一个 `ObservationRegistrar` 实例， // 用于管理观察事件的实例，当属性发生变化将通知所有 Observer internal let _$observationRegistrar = ObservationRegistrar&lt;Person&gt;() // access 方法会在属性被访问时调用，通过 ObservationRegistrar 的 access // 方法，并传入被访问的属性 keyPath，来触发事件 internal func access&lt;Member&gt;( keyPath: KeyPath&lt;Person, Member&gt; ) { _$observationRegistrar.access(self, keyPath: keyPath) } // withMutation 方法用于在修改属性时触发观察方法。在修改属性之前和之后分别触发观察事件， // 以便于观察者可以检测到属性的变化。这个方法通过 `ObservationRegistrar` 的 `withMutation` // 方法，传入被修改的属性的 keyPath 和一个闭包，这个闭包包含了对属性的修改操作 internal func withMutation&lt;Member, T&gt;( keyPath: KeyPath&lt;Person, Member&gt;, _ mutation: () throws -&gt; T ) rethrows -&gt; T { try _$observationRegistrar.withMutation(of: self, keyPath: keyPath, mutation) } } 其次，Member Attribute Macro 会为所有的属性添加 @ObservationTracked ，这个 Property Wrapper 会为属性添加 get 和 set 方法。 最后，Conformance Macro 会让 Person 这个 class 遵循 Observable协议。 通过这三个宏的改造，编译器将代码进行展开后，我们的真实代码类似以下： @Observable final class Person: ObservableObject { @ObservationTracked var name: String { get { … } set { … } } @ObservationTracked var age: Int { get { … } set { … } } @ObservationTracked var isFavorite: Bool { get { … } set { … } } internal let _$observationRegistrar = ObservationRegistrar&lt;Person&gt;() internal func access&lt;Member&gt;( keyPath: KeyPath&lt;Person, Member&gt; ) { _$observationRegistrar.access(self, keyPath: keyPath) } internal func withMutation&lt;Member, T&gt;( keyPath: KeyPath&lt;Person, Member&gt;, _ mutation: () throws -&gt; T ) rethrows -&gt; T { try _$observationRegistrar.withMutation(of: self, keyPath: keyPath, mutation) } } 虽然展开后的代码十分复杂，但是绝大多数代码都被 @Observable Macro 封装起来了，我们只需要输入以下的简洁版本即可实现。 @Observable final class Person { var name: String var age: Int var isFavorite: Bool } 当你需要对 Macro 展开，希望更好地理解程序代码时，你可以使用 Xcode 的 Expand Macro 功能对 Macro 进行源代码展开。任何在 Macro 生成的代码中出现的错误消息都会引导你去展开代码，从而快速地发现问题。 Swift Macro 为 Swift 实现更具可读性的 API 、构建更简洁的实现语法提供了一种新的模式。Macro 可以根据我们的需求，批量生成 Swift 代码，并在程序中使用 @ 或者 # 语法快速引入，简化了业务代码，也提高了可读性。 本文只是对 Swift Macro 进行一个初步的介绍以便于你从零到一认识。如果想学习更多，可以查看《Write Swift Macro》这个 Session ，通过实践来编写自己的 Swift Macro。另外如果想对 Swift Macro 的设计理念有更深刻的了解，可以学习《Expand on Swift》 这个 Session。 Swift Foundation 升级 Swift 这门编程语言的定位是一种可扩展的语言，其设计理念是使用清晰、简洁的代码，方便阅读和编写。其中的一些强大的特性，例如泛型、async/await 支持等等，可以支撑像 SwiftUI 或 SwiftData 这种更贴近自然描述的框架，从而允许开发者将关注点聚焦在业务上。 为了实现更加宽泛的可扩展性，我们需要将 Swift 适配较于 Objective-C 更多的领域，其中也包括更底层的操作系统领域，这一部分之前是由 C 或 C++ 进行编写的。 最近我们在 Swift 社区中，开源了 Foundation 的 Swift 重构版本，这个措施将使 Apple 以外的平台也可以享受到 Swift 带来的更加高效的性能和开发优势。但是也以为着我们需要用 Swift 对大量的 Objective-C 和 C 代码进行重构。 截止至 macOS Sonoma 和 iOS 17，一些基本类型已经完成了 Swift 重构版本，例如 Date、Calendar、Locale 和 AttributedString。另外 Swift 实现的 Encoder 和 Decoder 性能相较旧版本也有所提升。 下图是我们通过跑这些类库 Benchmark 测试用例，所得出的 Swift 重构版本的性能提升数据： 这些性能提升除了得益于 Swift 整体工具链的性能，另外还有一个原因就是 macOS Sonoma 系统上，我们避免了语言调用时的桥接成本（Bridging Cost），不需要再调用 Objective-C 的代码。我们从 enumerateDates 这个方法的调用数据统计中可以看到这个变化： Ownership &amp; Non-copyable Type 在对 Foundation 进行重构时，有时在操作系统的底层操作中，为了达到更高的性能水平，需要更细粒度的掌控。Swift 5.9 引入了“所有权”（Ownership）的概念，用来描述在你的代码中，当值在传递时，是哪段代码在“拥有”该值。 也许这个 Ownership 用文字描述起来有一些抽象，我们来看下示例： struct FileDescriptor { private var fd: CInt // 初始化方法，接受文件描述符作为参数 init(descriptor: CInt) { self.fd = descriptor } // 写入方法，接受一个 UInt8 数组作为缓冲区，并抛出可能的错误 func write(buffer: [UInt8]) throws { let written = buffer.withUnsafeBufferPointer { // 使用 Darwin.write 函数将缓冲区的内容写入文件描述符，并返回写入的字节数 Darwin.write(fd, $0.baseAddress, $0.count) } // ... } // 关闭方法，关闭文件描述符 func close() { Darwin.close(fd) } } 这是一段 FileDescriptor 的封装代码，我们可以用它更加方便的进行写文件操作。但是在使用的时候我们会经常犯一些错误，例如：你可能会在调用 close() 方法后，再执行 write(buffer:)方法。再比如：你可能会在 write(buffer:) 方法后，忘记调用 close()方法。 对于上面说的第二个场景，我们可以将 struct 修改成 class，通过在 deinit 方法中，调用 close() 方法，以便于在示例释放的时候，自动关闭。 class FileDescriptor { // ... deinit { self.close(fd) } } 但是这种做法也有它的缺点，例如它会造成额外的内存分配。虽然在通常情况下并不是大问题，但是在操作系统代码中某些受限的场景下是一个问题。 另外，class 构造出的示例，传递的都是引用。如果这个 FileDescriptor 在多个线程之间得到访问，导致竞态条件，或者持久化了这个实例导致引用计数始终大于 0 ，内存无法释放，进而引发内存泄漏。 再让我们重新回顾一下之前的 struct 版本。其实这个 struct 的行为也类似于引用类型。它会持有一个 fd 的整数，这个整数就好比引用了一个文件状态值，我们可以理解成打开了一个文件。如果我们复制了一个实例，相当于我们延长了这个文件的打开状态，如果后续代码中无意对其操作，这是不符合我们预期的。 Swift 的类型，无论是 struct 还是 class ，默认都是 Copyable 的。在大多数情况下，不会产生任何问题。但是有的时候，隐式复制的编译器行为，并不是我们希望的结果，尤其是在受限场景下，内存分配是我们要重点关注的问题。在 Swift 5.9 中，可以使用新的语法来强制声明禁止对类型进行隐式复制。当类型不能复制时，则可以像 class 一样提供一个 deinit 方法，在类型的值超出作用域时执行该方法。 struct FileDescriptor: ~Copyable { private var fd: CInt init(descriptor: CInt) { self.fd = descriptor } func write(buffer: [UInt8]) throws { let written = buffer.withUnsafeBufferPointer { Darwin.write(fd, $0.baseAddress, $0.count) } // ... } consuming func close() { Darwin.close(fd) } deinit { Darwin.close(fd) } } 像 FileDescriptor 这样被声明为 ~Copyable 的类型，我们称之为 Non-copyable types 。我们通过这样声明可以解决之前提出的第一个场景。 这里的 close 操作，其实就相当于上下文已经放弃了这个实例的 Ownership，这也就是上面代码中 consuming 关键字的含义。当我们将方法标注为 consuming 后，就同时声明了 Ownership 的放弃操作，也就意味着在调用上下文中，后文将无法使用该值。 当我们按照这个写法，在实际业务代码中使用的时候，我们会按照这样的执行顺序进行操作： let file = FileDescriptor(fd: descriptor) file.write(buffer: data) file.close() 因为 close 操作被我们标记了是 consuming 方法，则它必须在最后调用，以确保在此之前上下文代码具有该实例的 Ownership。如果我们写出了错误的调用顺序，编译器将会报错，并提示我们已经放弃了 Ownership ，无法继续调用其他方法。 Non-copyable Type 是 Swift 针对系统编程领域的一项强大的新功能，但目前仍处在早期阶段，后续版本将会不断迭代和扩展 Non-copyable Type 的功能。 与 C++ 的互操作性 混编代码 Swift 的推广普及其中一个重要的原因就是和 Objective-C 的互操作性。从一开始，开发者就可以使用 Swift 和 Objective-C 混编的方式，在项目中逐渐将代码替换成 Swift。 但是我们了解到，在很多项目中，不仅用到了 Objective-C，而且还用到了 C++ 来编写核心业务，互操作接口的编写比较麻烦。通常情况下，需要手动添加 bridge 层，Swift 经过 Objective-C ，再调用 C++ ，得到返回值后，再反向传出，这是一个十分繁琐的过程。 Swift 5.9 引入了 Swift 与 C++ 的互操作能力特性，Swift 会将 C++ 的 API 映射成 Swift API ，从而方便调用和获得返回值。 C++ 是一个功能强大的语言，具有自己的类、方法、容器等诸多概念。Swift 编译器能够识别 C++ 常见的习惯用法，因此大多数类型可以直接使用。例如下面这个 Person 类型，定义了 C++ 类型中常见的五个成员函数：拷贝构造函数、转移（有些中文教材也叫做移动）构造函数、（两个）赋值重载运算符、析构函数。 // Person.h struct Person { // 拷贝构造函数: 通过从另一个Person对象进行拷贝来构造新的Person对象 Person(const Person &amp;); // 转移构造函数: 通过从另一个Person对象进行移动来构造新的Person对象 Person(Person &amp;&amp;); // 拷贝赋值重载运算符: 将另一个Person对象的值赋给当前对象 Person &amp;operator=(const Person &amp;); // 转移赋值重载运算符: 通过移动另一个Person对象的值来赋给当前对象 Person &amp;operator=(Person &amp;&amp;); // 析构函数: 清理Person对象所持有的资源 ~Person(); // string 类型，存储人员姓名 std::string name; // const 代表只读，用于返回人员年龄 unsigned getAge() const; }; // 函数声明，返回一个 Person 对象的 vector 容器 std::vector&lt;Person&gt; everyone(); 我们通过 Swift 可以直接调用这个 C++ 的 struct ，也可以直接使用上面定义的 vector&lt;Person&gt; 。补充一句：C++ 的常规容器，例如：vector、map 等，Swift 均是可以直接访问的。 // Client.swift func greetAdults() { for person in everyone().filter { $0.getAge() &gt;= 18 } { print("Hello, \(person.name)!") } } 正如 greetAdults() 方法描述的这样，我们在 Swift 中可以直接调用 C++ 定义的类型，从而达到和 C++ 的优秀交互能力。 下面来说说“反向”用 C++ 调用 Swift 的场景。C++ 中使用 Swift 的代码基于与 Objective-C 相同的机制，即编译器会自动生成一个 Header 文件，我们可以在 Xcode 中找到生成后的 C++ header。然而与 Objective-C 不同的是，你不需要使用 @objc 这个注释对方法进行标注。C++ 大多数情况下是可以使用 Swift 完整的 API，包括属性、方法和初始化方法，无需任何桥接成本。 举个例子： // Geometry.swift struct LabeledPoint { var x = 0.0, y = 0.0 var label: String = "origin" mutating func moveBy(x deltaX: Double, y deltaY: Double) { … } var magnitude: Double { … } } 这是一个 Swift 定义的 struct ，下面我们在 C++ 文件中来使用它： // C++ client #include &lt;Geometry-Swift.h&gt; void test() { Point origin = Point() Point unit = Point::init(1.0, 1.0, "unit") unit.moveBy(2, -2) std::cout &lt;&lt; unit.label &lt;&lt; " moved to " &lt;&lt; unit.magnitude() &lt;&lt; std::endl; } 我们可以看到，在遵循 C++ 语法习惯的前提下，所有的方法名都没有发生变化，无需对 Swift 代码进行定制化修改即可完成调用。 Swift 的 C++ 交互让大家在业务开发中更加容易。许多 C++ 习惯用法可以直接在 Swift 中表达，通常是自动完成的，但偶尔需要一些标记（annotation）来指示所需的语义。而且，可以直接从 C++ 访问 Swift API，无需注释或更改代码，提升了开发效率，也降低了迁移成本。 有些地方会将 annotation 翻译成“注释”，但是校对者 stevapple 在此处建议使用标记进行翻译，因为是用作编译器来声明额外的语义操作。个人也比较采纳。 C++ 的交互也是一个不断迭代的 feature，如果想了解更多，可以参看《Mix Swift and C++》这个 session。 构建系统 与 C++ 的交互在语言层面上十分重要，但是我们也不能忽视构建系统的适配。因为使用 Xcode 和 Swift Package Manager 来替换 C++ 的整套构建系统，也是开发者的一个障碍。 这也就是为什么我们要将这个 topic 单独拿出来讨论。Swift 与 CMake 开发社区合作改进了 CMake 对 Swift 的支持。你可以将 Swift 声明为项目使用的一种语言，并将 Swift 源文件加入 target 中，从而将 Swift 代码集成到 CMake 构建中。 # CMake project(PingPong LANGUAGES CXX Swift) add_library(PingPong Ping.swift, Pong.swift, TableTennisUtils.cpp ) 值得一提的是，你也可以在单个 Target 中混合使用 C++ 和 Swift ，CMake 将确保分别编译每个语言，并链接适用于两种语言适当的系统库和 Runtime 库。这也就意味着，你可以使用 Swift 来逐步取代跨平台的 C++ 项目。另外，Swift 社区还提供了一个包含 Swift 和混合 C++/Swift Target 的 CMake 实例存储库，其中包括使用桥接和生成的头文件，来帮助你上手。 Swift Concurrency - Actor 执行器 几年前，我们引入了基于 async/await 、Structured Concurrency 以及 actors 构建的并发模型。Swift 的并发模型是一个通用抽象模型，可以适配不同的环境和库。在这个通用抽象模型中有两个主要部分，Tasks 和 Actors： Tasks：代表可以在任意位置顺序执行的逻辑。如果有 await 关键字，tasks 可以被挂起，等其执行完成后继续恢复执行； Actors：是一种同步机制，提供对隔离状态的互斥访问权。从外部进入一个 actor 需要进行 await ，否则当前可能会将 tasks 挂起。 在内部实现上，Tasks 在全局并发池（Global Concurrent Pool）上执行。全局并发池根据环境决定如何调度任务。在 Apple 平台中，Dispatch 类库为每个系统提供了针对性优化的调度策略。 但是和前文问题一样，我们考虑更受限的环境下，多线程调度的开销我们无法接受。在这种情况下，Swift 的并发模型则会采用单线程的协同队列（Single-threaded Cooperative Queue）进行工作。同样的代码在多种情况下都可以正常工作，因为通用抽象模型可以描述的场景很广，可以覆盖到更多 case。 在标准的 Swift 并发运行场景下， Actors 是通过无锁任务队列（Lock-free Queue of Tasks）来实现的，但这不是唯一的实现方式。在受限环境下，没有原子操作（Atomics），可以使用其他的并发原语（Concurrency Primitive），比如自旋锁。如果考虑单线程环境，则不需要同步机制，但 Actors 模型仍然可被通用模型覆盖到。如此你可以在单线程和多线程环境中，使用同一份代码。 在 Swift 5.9 中，自定义 Actor 执行器（Executors）允许实现特定的同步机制，这使 Actors 变得更加灵活。我们来看一个例子： // Custom actor executors // 定义一个名为MyConnection的actor类，用于管理数据库连接 actor MyConnection { private var database: UnsafeMutablePointer&lt;sqlite3&gt; // 初始化方法，接收一个文件名作为参数，并抛出异常 init(filename: String) throws { … } // 用于清理旧条目的方法 func pruneOldEntries() { … } // 根据给定的名称和类型，从数据库中获取一个条目 func fetchEntry&lt;Entry&gt;(named: String, type: Entry.Type) -&gt; Entry? { … } } // 在外部调用时使用"await"来暂停当前任务，等待pruneOldEntries方法完成 await connection.pruneOldEntries() 这是一个管理数据库连接的 Actor 例子。Swift 确保代码对 Actor 互斥访问，所以不会出现对数据库的并发访问。但是如果你需要对同步访问进行控制要如何做呢？例如，当你连接数据库的时候，你想在某个队列上执行，而不是一个未知的、未与其他线程共享的队列。在 Swift 5.9 中，可以自定义 actor 执行器，可以这样实现： actor MyConnection { private var database: UnsafeMutablePointer&lt;sqlite3&gt; // 执行方法的队列 private let queue: DispatchSerialQueue // 这里自定义 actor 的执行器，nonisolated 定义为它是一个非孤立方法，即不需要在外部使用 await 关键字 nonisolated var unownedExecutor: UnownedSerialExecutor { queue.asUnownedSerialExecutor() } init(filename: String, queue: DispatchSerialQueue) throws { … } func pruneOldEntries() { … } func fetchEntry&lt;Entry&gt;(named: String, type: Entry.Type) -&gt; Entry? { … } } await connection.pruneOldEntries() 上述代码中，我们为 actor 添加了一个串行调度队列，并且提供了一个 unownedExecutor 的实现，用于生成与该队列关联的执行器。通过这个改变，所有 actor 实例的同步方法将通过这个队列来执行。 当你在外部调用 await connection.pruneOldEntries() 时，其实现在真正的行为是在上方的队列里调用了 dispatchQueue.async 。有了这个自定义执行器后，我们可以全方位控制 Actor 的方法调度，甚至可以与未使用 Actor 的方法混用并调度他们的执行顺序。 我们可以通过调度队列对 actor 进行同步调度，是因为调度队列遵循了新的 SerialExecutor 协议。开发者可以通过实现一个符合该协议的类，从而定义自己的调度机制。 // Executor protocols protocol Executor: AnyObject, Sendable { // 方法 1 func enqueue(_ job: consuming ExecutorJob) } protocol SerialExecutor: Executor { // 方法 2： func asUnownedSerialExecutor() -&gt; UnownedSerialExecutor // 方法 3： func isSameExclusiveExecutionContext(other executor: Self) -&gt; Bool } extension DispatchSerialQueue: SerialExecutor { … } 在这个协议中包括了一些核心操作： 检查代码是否已经在执行器上下文中执行：如上代码中的方法 3 isSameExclusiveExecutionContext(other:)。例如：你可以实现是否在主线程上执行。 可以获取这个 Executor 对应的执行器实例，并访问它：如上代码中的方法 2 asUnownedSerialExecutor()。 将某个 Job 的所有权给到这个执行器：如上述代码中的方法 1 enqueue(_:)。 Job 是需要在执行器上同步完成异步任务，这样的一个概念。从运行表现上来说，还是列举上面数据库连接的例子，enqueue方法将会在我们声明的队列上，调用 dispatchQueue.async 方法。 Swift 并发编程目前已经有了几年的经验，Tasks 和 Actor 这套模型也覆盖了诸多并发场景。从 iPhone 到 Apple Watch ，再到 Server ，其已适应不同的执行环境。这是一套复杂却又实用的系统，如果你希望了解更多，可以查看《Behind the Scenes》和《Beyond the basics of Structured Concurrency》这两个 Session。 FoundationDB 最后我们介绍一点额外的东西，FoundationDB。这是一个分布式数据库，用于在普通硬件上运行的可扩展数据库解决方案。目前已经支持 macOS 、Linux 和 Windows。 FoundationDB 是一个开源项目，代码量很大，且使用 C++ 编写。这些代码是强异步的，具有自己的分布式 Actor 和 Runtime 实现。FoundationDB 项目希望对其代码进行现代化改造，并且认为 Swift 在性能、安全性和代码可读性上与其需求十分匹配。但是完全使用 Swift 重构是一个非常冒险的任务，所以在最新版代码中，开发人员利用 Swift 与 C++ 的交互新特性，进行部分的重构。 首先我们来看一下 FoundationDB 部分的 Actor 代码片段 C++ 实现： // FoundationDB的“master data” actor的C++实现 // 异步函数，用于获取版本号 ACTOR Future&lt;Void&gt; getVersion(Reference&lt;MasterData&gt; self, GetCommitVersionRequest req) { // 查找请求代理的迭代器 state std::map&lt;UID, CommitProxyVersionReplies&gt;::iterator proxyItr = self-&gt;lastCommitProxyVersionReplies.find(req.requestingProxy); ++self-&gt;getCommitVersionRequests; // 如果在映射中找不到代理的迭代器，则发送一个“Never”的响应并返回 if (proxyItr == self-&gt;lastCommitProxyVersionReplies.end()) { req.reply.send(Never()); return Void(); } // 等待直到最新的请求编号至少达到 req.requestNum - 1 wait(proxyItr-&gt;second.latestRequestNum.whenAtLeast(req.requestNum - 1)); // 在回复的映射中查找与请求编号对应的回复 auto itr = proxyItr-&gt;second.replies.find(req.requestNum); if (itr != proxyItr-&gt;second.replies.end()) { // 如果找到回复，则将其作为响应发送并返回 req.reply.send(itr-&gt;second); return Void(); } // ... } 这段代码有很多内容，你并不需要了解这段 C++ 代码。其中，我只想指出一个关键的地方：因为 C++ 没有 async/await ，所以 FoundationDB 使用了类似于预处理器（Preprocessor）的方式进行模拟实现。 通过对应的编号进行筛选，从而显式实现了消息匹配，从而将正确的结果返回。最后，FoundationDB 有自己的引用计数智能指针来帮助自动管理内存。上述 C++ 代码描述的就是这样的一个过程。 但如果我们使用 Swift ，这个方法就可以直接使用异步函数的特性，使用 await 来表示对于请求的匹配，就节省了上述大量的代码逻辑。 // FoundationDB的“master data” actor的Swift实现 // 异步函数，用于获取版本号 func getVersion( myself: MasterData, req: GetCommitVersionRequest ) async -&gt; GetCommitVersionReply? { // 增加getCommitVersionRequests计数 myself.getCommitVersionRequests += 1 // 检查是否存在请求代理的最后版本回复 guard let lastVersionReplies = lastCommitProxyVersionReplies[req.requestingProxy] else { return nil } // ... // 等待直到latestRequestNum至少达到req.requestNum - 1 var latestRequestNum = try await lastVersionReplies.latestRequestNum .atLeast(VersionMetricHandle.ValueType(req.requestNum - UInt64(1))) // 如果存在请求编号对应的最后回复，则返回该回复 if let lastReply = lastVersionReplies.replies[req.requestNum] { return lastReply } } 是不是可读性提高了不少？ 另外，我们在这里使用了很多 C++ 类型，C++ 中的 MasterData 类型使用了引用计数智能指针。通过在 C++ 中对类型进行标注，Swift 编译器可以像任何其他类一样使用该类型，自动管理引用计数。 从这个例子中，我们获取到的经验是，我们可以在需要的时候，使用 Swift 的优势来改写逻辑，与现有的 C++ 代码进行接口互调操作，实现渐进式的代码替换，最终也可以推进项目 Swift 化的进程。 总结 这个 Session 中我们讨论了很多内容，不乏 Swift 的一些新的语法特性和 Swift Macros。这些功能可以实现更加灵活和健壮的 API，帮助你更好地编写高质量代码。 另外，我们也大篇幅的讨论了在受限环境下使用 Swift 的优势，以及 Swift 如何灵活的适配多种平台设备、语言，这些也为我们在编写代码中，获得更多的思考。 这些特性的出现和设计，都是通过 Swift 社区中从 idea 、公开讨论、结果反馈等等流程中孕育而生的。感谢各位开发者的支持，让 Swift 5.9 这门编程语言更加健壮。]]></summary></entry><entry><title type="html">PancakeHunny 闪电贷 LP 池操控攻击分析</title><link href="https://www.desgard.com/2021/11/03/defi-hunny-attack-analysis.html" rel="alternate" type="text/html" title="PancakeHunny 闪电贷 LP 池操控攻击分析" /><published>2021-11-03T00:00:00-08:00</published><updated>2021-11-03T00:00:00-08:00</updated><id>https://www.desgard.com/2021/11/03/defi-hunny-attack-analysis</id><content type="html" xml:base="https://www.desgard.com/2021/11/03/defi-hunny-attack-analysis.html"><![CDATA[<h1 id="背景">背景</h1>

<p>2021 年 10 月 20 日 UTC 时间上午 9 点，PancakeHunny 平台遭遇闪电贷智能合约攻击，攻击者通过操纵 PCS 上的 WBNB/TUSD 的流动性从而操纵了兑换比例，实现了 HUNNY 铸币合约的大量铸币，完成攻击。</p>

<p>最终攻击者获利 230 万美元（64.2 万是稳定币 + 435.31 ETH），并且大量铸造 HUNNY 代币，将 HUNNY 的价格从 0.3 抛售到 0.1 美元。
​</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/1635583246116-9c41c78d-cfc2-4008-8ad1-2682ae038fe4.png" alt="" /></p>

<p>这一操作的 TxHash 从 bscscan 上可以找到：<a href="https://bscscan.com/tx/0x1b698231965b72f64d55c561634600b087154f71bc73fc775622a45112a94a77">0x1b698231965b72f64d55c561634600b087154f71bc73fc775622a45112a94a77</a>。
​
下面我们来复盘一下整个攻击手法和流程。</p>

<h1 id="代码中的根本原因">代码中的根本原因</h1>

<p>可以查看合约 <a href="https://bscscan.com/address/0x27d4ca4bb855e435959295ec273fa16fe8caea14#code">VaultStrategyAlpacaRabbit</a>，这个合约是可升级合约的原合约地址。目前该合约仍旧由线上 <a href="https://bscscan.com/address/0xef43313e8218f25fe63d5ae76d98182d7a4797cc">TUSD 单币池合约地址</a>进行代理转发（也就是线上还没有进行更换），但是目前官方已经发现了问题，已经关闭了该池的铸币（那其实还不如直接存 Alpaca Finance）。
​
我们在 <a href="https://bscscan.com/address/0x27d4ca4bb855e435959295ec273fa16fe8caea14#code">VaultStrategyAlpacaRabbit</a> 合约中，可看到以下代码：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/1635956502729-dab865ce-a8bc-4ee7-9104-991739decb3b.png" alt="" />
​</p>

<p>在上述代码中，黄色高亮的一行就是此次攻击的根本原因。原因就是因为这个 swap 的 Path 最终选用的是 <code class="language-plaintext highlighter-rouge">[ALPACA, WBNB, TUSD]</code> ，<strong>然而 TUSD/WBNB 的 LP Token 其流动性仅有 2 美元（这是目前的情况，可以</strong><a href="https://pancakeswap.finance/info/pool/0x1b011a21c02194a449e32f729489d299f907e71a"><strong>查看 PCS 的流动性数据</strong></a><strong>）</strong>，于是攻击者就通过闪电贷放大资金量，从而控制这组 LP Token 的兑换汇率，从而进行攻击。
​</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/1635957697293-931a04a8-5b51-416f-999b-f2a7fe26ab52.png" alt="" /></p>

<p>接下来我们来分步骤解析这个过程：
​</p>

<ul>
  <li>攻击者利用闪电贷，借出 270 万 TUSD，并且全部通过 <code class="language-plaintext highlighter-rouge">[TUSD, WBNB]</code> 的 Path 兑换成了 WBNB。根据 AMM 的恒定乘积公式 \(x \times y = k\) ，由于大量的 TUSD 进入到了 TUSD/WBNB Lp 池中，<strong>所以通过十分少量的 WBNB 沿着相反的 Path 就能兑换出大量的 TUSD</strong>。</li>
  <li>第二步，攻击者会将一笔可观的 TUSD 数额放入 TUSD 单币池中，让其占据了该池 99% 的收益。此时因为步骤一种操控了 Lp 池，大量的 TUSD 会被兑换出来。</li>
  <li>第三步，攻击者会调用 <code class="language-plaintext highlighter-rouge">getReward()</code> 方法，这个方法会调用 <code class="language-plaintext highlighter-rouge">_withdrawStakingToken()</code> 方法，其中会返回 <code class="language-plaintext highlighter-rouge">withdrawAmount</code> 这个变量。</li>
</ul>

<div class="language-rust highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">withdrawAmount</span> <span class="o">=</span> <span class="n">_stakingToken</span><span class="nf">.balanceOf</span><span class="p">(</span><span class="nf">address</span><span class="p">(</span><span class="n">this</span><span class="p">))</span><span class="nf">.sub</span><span class="p">(</span><span class="n">stakingTokenBefore</span><span class="p">);</span>
</code></pre></div></div>

<p>它会通过 <code class="language-plaintext highlighter-rouge">_stakingToken</code> 也就是我们的 TUSD 总量来计算。而 <code class="language-plaintext highlighter-rouge">withdrawAmount</code> 就是用来传入到 <code class="language-plaintext highlighter-rouge">minter</code> 中，其价值的 30% 为总量负责铸造 HUNNY 代币的数量控制变量，从而造成大量的 <code class="language-plaintext highlighter-rouge">HUNNY</code> 被铸造。</p>

<ul>
  <li>攻击者抛售大量的 <code class="language-plaintext highlighter-rouge">HUNNY</code> 完成此次经济攻击。</li>
</ul>

<h1 id="复盘">复盘</h1>

<p>攻击者完成本次攻击，是与以往的 <code class="language-plaintext highlighter-rouge">BUNNY</code> 攻击有所区别的，<code class="language-plaintext highlighter-rouge">BUNNY</code> 中的错误实在是太低级了，使用了账户余额的代币数量来铸造 <code class="language-plaintext highlighter-rouge">BUNNY</code> 。虽然 <code class="language-plaintext highlighter-rouge">HUNNY</code> 通过使用增量变量的方式避免了 <code class="language-plaintext highlighter-rouge">BUNNY</code> 的漏洞，但对于 LP Token 市值太低容易操纵这一环节没有戒备心，从而导致了经济漏洞。
​</p>

<p>反思：在制作机枪池的时候，如果有 Minter 进行铸造操纵，一定要慎之又慎，来验证每一步用到的数量关系，再进行代码编写。</p>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="Blockchain" /><category term="DeFi" /><category term="Web3" /><summary type="html"><![CDATA[背景 2021 年 10 月 20 日 UTC 时间上午 9 点，PancakeHunny 平台遭遇闪电贷智能合约攻击，攻击者通过操纵 PCS 上的 WBNB/TUSD 的流动性从而操纵了兑换比例，实现了 HUNNY 铸币合约的大量铸币，完成攻击。 最终攻击者获利 230 万美元（64.2 万是稳定币 + 435.31 ETH），并且大量铸造 HUNNY 代币，将 HUNNY 的价格从 0.3 抛售到 0.1 美元。 ​ 这一操作的 TxHash 从 bscscan 上可以找到：0x1b698231965b72f64d55c561634600b087154f71bc73fc775622a45112a94a77。 ​ 下面我们来复盘一下整个攻击手法和流程。 代码中的根本原因 可以查看合约 VaultStrategyAlpacaRabbit，这个合约是可升级合约的原合约地址。目前该合约仍旧由线上 TUSD 单币池合约地址进行代理转发（也就是线上还没有进行更换），但是目前官方已经发现了问题，已经关闭了该池的铸币（那其实还不如直接存 Alpaca Finance）。 ​ 我们在 VaultStrategyAlpacaRabbit 合约中，可看到以下代码： ​ 在上述代码中，黄色高亮的一行就是此次攻击的根本原因。原因就是因为这个 swap 的 Path 最终选用的是 [ALPACA, WBNB, TUSD] ，然而 TUSD/WBNB 的 LP Token 其流动性仅有 2 美元（这是目前的情况，可以查看 PCS 的流动性数据），于是攻击者就通过闪电贷放大资金量，从而控制这组 LP Token 的兑换汇率，从而进行攻击。 ​ 接下来我们来分步骤解析这个过程： ​ 攻击者利用闪电贷，借出 270 万 TUSD，并且全部通过 [TUSD, WBNB] 的 Path 兑换成了 WBNB。根据 AMM 的恒定乘积公式 \(x \times y = k\) ，由于大量的 TUSD 进入到了 TUSD/WBNB Lp 池中，所以通过十分少量的 WBNB 沿着相反的 Path 就能兑换出大量的 TUSD。 第二步，攻击者会将一笔可观的 TUSD 数额放入 TUSD 单币池中，让其占据了该池 99% 的收益。此时因为步骤一种操控了 Lp 池，大量的 TUSD 会被兑换出来。 第三步，攻击者会调用 getReward() 方法，这个方法会调用 _withdrawStakingToken() 方法，其中会返回 withdrawAmount 这个变量。 withdrawAmount = _stakingToken.balanceOf(address(this)).sub(stakingTokenBefore); 它会通过 _stakingToken 也就是我们的 TUSD 总量来计算。而 withdrawAmount 就是用来传入到 minter 中，其价值的 30% 为总量负责铸造 HUNNY 代币的数量控制变量，从而造成大量的 HUNNY 被铸造。 攻击者抛售大量的 HUNNY 完成此次经济攻击。 复盘 攻击者完成本次攻击，是与以往的 BUNNY 攻击有所区别的，BUNNY 中的错误实在是太低级了，使用了账户余额的代币数量来铸造 BUNNY 。虽然 HUNNY 通过使用增量变量的方式避免了 BUNNY 的漏洞，但对于 LP Token 市值太低容易操纵这一环节没有戒备心，从而导致了经济漏洞。 ​ 反思：在制作机枪池的时候，如果有 Minter 进行铸造操纵，一定要慎之又慎，来验证每一步用到的数量关系，再进行代码编写。]]></summary></entry><entry><title type="html">LP Token 价格计算推导及安全性</title><link href="https://www.desgard.com/2021/09/06/defi-lp-price.html" rel="alternate" type="text/html" title="LP Token 价格计算推导及安全性" /><published>2021-09-06T00:00:00-08:00</published><updated>2021-09-06T00:00:00-08:00</updated><id>https://www.desgard.com/2021/09/06/defi-lp-price</id><content type="html" xml:base="https://www.desgard.com/2021/09/06/defi-lp-price.html"><![CDATA[<h1 id="背景">背景</h1>

<p>在实现 CakeBot 的 USDT/USDC 池时，需要计算 LP Token 的代币价值，从而方便的给用户提示 LP Token 当前准确的价格，来计算收益率。所以对 LP Token 的价值计算做了一点深入的研究，并且还翻阅到 Alpha Finance 团队的关于安全获取 LP 价格的方法。
本位将这些学习笔记分享给大家。
​</p>

<h1 id="一般-lp-token-价格的获取方法">一般 LP Token 价格的获取方法</h1>

<p>我们知道对于一般 Token 的价格，在 Cex 中其实是市场上交易撮合的成交价。在 Dex 中，由于 AMM 做市商模型通过一组 LP 来构建价格的锚定。所以如果我们想获取到一个 Token 的价格，都是通过对于稳定币 USDT、USDC 或者 BUSD 的币对关系，从而反映现实世界的价格。
​</p>

<p>我们知道 LP Token 是不具有流动性池的，如果有那就是套娃了。那么我们应该如何去计算价格呢？其实我们只需要用总增发量和货币价格反推即可。
​</p>

\[Cap_x = P_x \times T_x\]

<p>​</p>

<p>任意一个 Token X 的总市值是 $Cap_x$，是用当前的价格 $P_x$ 和当前总铸造数量 $T_x$相乘可得。对于 LP Token，我们可以用这个公式来反推币价。因为在 LP Token 中，总市值是可以通过两种币的数量和对应价格求得，并且总的制造数量也是已知的。
​</p>

<p>所以我们可以如此计算 LP Token 总价格：
​</p>

\[P_{LP} = \frac{Cap_{LP}}{T_{LP}} = \frac{r_0 \times price_0 + r_1 \times price_1}{totalSupply}\]

<p>​</p>

<p>其中，$r_0$和 $r_1$就是 LP Token 合约中两种代币的存量，$price_0$和 $price_1$分别代表 $r_0$和 $r_1$ 对应 Token 的价格。市面上无论 BSC、ETH 还是 Polygon 还是 Heco 链等，其 LP 代币基本都是 fork Uniswap 的，所以 $r_0$和 $r_1$、$price_0$和 $price_1$ 都是能拿到的。
​</p>

<p>上面的公式我们其实可以看出，是通过市值反推价格，也没有什么巨大的逻辑问题。当我们需要访问其币价的时候已经可以满足需求。在 Web3.js 前端中，我们就可以照此拿到结果。</p>

<div class="language-javascript highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">export</span> <span class="kd">const</span> <span class="nx">getLpTokenPrice</span> <span class="o">=</span> <span class="k">async</span> <span class="p">(</span>
  <span class="nx">lpAddress</span><span class="p">:</span> <span class="nx">string</span><span class="p">,</span>
  <span class="nx">lib</span><span class="p">:</span> <span class="nx">any</span><span class="p">,</span>
  <span class="nx">price0</span><span class="p">:</span> <span class="nx">BigNumber</span><span class="p">,</span>
  <span class="nx">price1</span><span class="p">:</span> <span class="nx">BigNumber</span>
<span class="p">)</span> <span class="o">=&gt;</span> <span class="p">{</span>
  <span class="kd">const</span> <span class="nx">lpToken</span> <span class="o">=</span> <span class="nx">getPancakeLp</span><span class="p">(</span><span class="nx">lib</span><span class="p">,</span> <span class="nx">lpAddress</span><span class="p">);</span>
  <span class="kd">let</span> <span class="p">[</span><span class="nx">r0</span><span class="p">,</span> <span class="nx">r1</span><span class="p">]</span> <span class="o">=</span> <span class="p">(</span><span class="k">await</span> <span class="nx">lpToken</span><span class="p">.</span><span class="nx">getReserves</span><span class="p">()).</span><span class="nx">map</span><span class="p">((</span><span class="nx">n</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="nx">bignumberToBN</span><span class="p">(</span><span class="nx">n</span><span class="p">));</span>
  <span class="kd">let</span> <span class="nx">totalSupply</span> <span class="o">=</span> <span class="nx">bignumberToBN</span><span class="p">(</span><span class="k">await</span> <span class="nx">lpToken</span><span class="p">.</span><span class="nx">totalSupply</span><span class="p">());</span>
  <span class="k">return</span> <span class="nx">r0</span>
    <span class="p">.</span><span class="nx">multipliedBy</span><span class="p">(</span><span class="nx">price0</span><span class="p">)</span>
    <span class="p">.</span><span class="nx">plus</span><span class="p">(</span><span class="nx">r1</span><span class="p">.</span><span class="nx">multipliedBy</span><span class="p">(</span><span class="nx">price1</span><span class="p">))</span>
    <span class="p">.</span><span class="nx">dividedBy</span><span class="p">(</span><span class="nx">totalSupply</span><span class="p">);</span>
<span class="p">};</span>
</code></pre></div></div>

<p>至此，我的需求完成。</p>

<h1 id="延时喂价漏洞">延时喂价漏洞</h1>

<p>对于上文公式：
​</p>

\[price_{lp}= \frac{r_0 \times price_0 + r_1 \times price_1}{totalSupply}\]

<p>其实乍一看是不存在问题的。但是如果我们所做的需求，不仅仅是一个价格展示，而是一个借贷系统，用这种方式来获取清算系数，就会<strong>存在被闪电贷的风险</strong>。虽然 $price_0$和 $price_1$不能被操控，但是 $r_0$和 $r_1$是可以的。黑客可以通过操作 $r_0$ 和 $r_1$，从而对价格实现控制。</p>

<p>之前漫雾团队写过一篇<a href="https://mp.weixin.qq.com/s/ues5U9Bl971hSqGO1a4SYA">「Warp Finance 被黑详解」</a>的分析，采用了如下攻击流程：</p>

<ol>
  <li>通过 dydx 与 Uniswap 闪电贷借出 DAI 和 WETH；</li>
  <li>用小部分 DAI 和 WETH 在 Uniswap 的 WETH-DAI LP 中添加流动性，获得 LP Token；</li>
  <li>将 LP Token 抵押到 Wrap Finance 中；</li>
  <li>用巨量的 WETH 兑换成 DAI，因为 WETH 迅速进入了 WETH-DAI 流动池，总数量大增。但是由于价格使用的是 Uniswap 的预言机，访问的是 Uniswap 的 LP 池，所以 WETH 的价格并未发生变化。从而导致 Wrap Finance 中的 WETH-DAI LP Token 价格迅速提高；</li>
  <li>由于 LP Token 单价变高，导致黑客抵押的 LP Token 可以借出更多的稳定币来获息。</li>
</ol>

<p>​</p>

<p>这里，我们发现漏洞的关键地方，其实是 $price$ 计算对于借贷项目中，使用的是他人的 LP 合约，还未等套利者来平衡价格，从而终究留出了时间差。
​</p>

<p>为了解决这个问题，如果我们可以找到一种方式，从而规避价格查询，就能大概率防止上述漏洞。这里，Alpha Finance 给出了另外一个推导公式。</p>

<h1 id="获取公平-lp-价格方法">获取公平 LP 价格方法</h1>

<p>首先我们在一个 LP 池中，我们能保证的是恒定乘积 $K$ 值的大小，我们定义价格比值是 $P$，那么我们会有以下关系式：
​</p>

\[\begin{cases}
K=r_0 \times r_1 \\
P = \frac{r_1}{r_0}
\end{cases}\]

<p>​</p>

<p>因为 $r_0$ 和 $r_1$ 在旧方法中是可以被操纵的，所以我们用 $K$ 和 $P$ 来反解真实的 $r’_{0}$ 和 $r’_1$ ：
​</p>

\[\begin{cases}
r'_0 = \sqrt{K / P} \\
r'_1 = \sqrt{K \times P}
\end{cases}\]

<p>如此，我们在带入一开始计算 $price_{lp}$的公式中：
​</p>

\[\begin{align}
price_{lp}   &amp;= \frac{r'_0 \times price_0 + r'_1 \times price_1}{totalSupply} \\
   &amp; = \frac{\sqrt{K/P}·price_0 + \sqrt{K·P}·price_1}{totalSupply} \\
    &amp; = \frac{\sqrt{K · \frac{price_1}{price_0}·price_0^2} + \sqrt{K·\frac{price_0}{price_1}·price_1^2}}{totalSupply} \\
&amp; = \frac{2\sqrt{K·price_0·price_1}}{totalSupply} \\
&amp; = 2 \frac{\sqrt{r_0·r_1}·\sqrt{price_0 · price_1}}{totalSupply}
\end{align}\]

<p>我们可以发现，最终 Alpha Finance 给我们的推导式中，不会存在独立的 $r_0$ 和 $r_1$ ，取而代之的是它们的恒定乘积 $K$。</p>

<h1 id="攻击可能性分析">攻击可能性分析</h1>

<p>使用以上公式，我们可以真正的避免攻击吗？</p>

<ol>
  <li>​$price_0$和 $price_1$ 首先是可信源获取的正确价格，无法操纵；</li>
  <li>$totalSupply$ 只是改变了质押数量，其变化与质押的两个代币数量有关系；</li>
  <li>对于 $r_0$ 和 $r_1$ ，在 Alpha Finance 的博客中提供了两种思路：
    <ol>
      <li>直接进行代币兑换（类似于上述攻击手段），由于 $r_0 \times r_1$ 是定值 $K$，所以无论如何变化都不会影响计算结果；</li>
      <li>直接将 Token 打入 LP Token 合约地址中，由于 $r_0$ 和 $r_1$ 都是在二次根式下，所以付出 $x$ 倍的成果，最终只能获得 $\sqrt{x}$ 倍的收益，这显然是亏本的；</li>
    </ol>
  </li>
</ol>

<p>综上，在已知情况下，是可以有效避免攻击的。</p>

<h1 id="总结">总结</h1>

<p>通过这次对 LP Token 价格计算的研究，并且对延时喂价漏洞的探求，了解了 LP 抵押使用一般方式计算带来的风险。计算价格的需求，一定要根据所做业务的类型，谨慎选择。</p>

<h1 id="参考链接">参考链接</h1>

<ul>
  <li><a href="https://blog.alphafinance.io/fair-lp-token-pricing/">Alpha Finance 关于获取公平 LP 价格的方法</a></li>
  <li><a href="https://ethfans.org/posts/a-safe-way-to-get-the-prices-of-lp-tokens">一种安全的 LP 价格的获取方法曾汨</a></li>
</ul>

<hr />

<blockquote>
  <p>欢迎大家使用我个人研发的 <a href="https://cakebot.finance/">Cakebot Finance</a> 来体验去中心化 DAPP 挖矿。</p>
</blockquote>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="Blockchain" /><category term="DeFi" /><category term="Web3" /><summary type="html"><![CDATA[背景 在实现 CakeBot 的 USDT/USDC 池时，需要计算 LP Token 的代币价值，从而方便的给用户提示 LP Token 当前准确的价格，来计算收益率。所以对 LP Token 的价值计算做了一点深入的研究，并且还翻阅到 Alpha Finance 团队的关于安全获取 LP 价格的方法。 本位将这些学习笔记分享给大家。 ​ 一般 LP Token 价格的获取方法 我们知道对于一般 Token 的价格，在 Cex 中其实是市场上交易撮合的成交价。在 Dex 中，由于 AMM 做市商模型通过一组 LP 来构建价格的锚定。所以如果我们想获取到一个 Token 的价格，都是通过对于稳定币 USDT、USDC 或者 BUSD 的币对关系，从而反映现实世界的价格。 ​ 我们知道 LP Token 是不具有流动性池的，如果有那就是套娃了。那么我们应该如何去计算价格呢？其实我们只需要用总增发量和货币价格反推即可。 ​ \[Cap_x = P_x \times T_x\] ​ 任意一个 Token X 的总市值是 $Cap_x$，是用当前的价格 $P_x$ 和当前总铸造数量 $T_x$相乘可得。对于 LP Token，我们可以用这个公式来反推币价。因为在 LP Token 中，总市值是可以通过两种币的数量和对应价格求得，并且总的制造数量也是已知的。 ​ 所以我们可以如此计算 LP Token 总价格： ​ \[P_{LP} = \frac{Cap_{LP}}{T_{LP}} = \frac{r_0 \times price_0 + r_1 \times price_1}{totalSupply}\] ​ 其中，$r_0$和 $r_1$就是 LP Token 合约中两种代币的存量，$price_0$和 $price_1$分别代表 $r_0$和 $r_1$ 对应 Token 的价格。市面上无论 BSC、ETH 还是 Polygon 还是 Heco 链等，其 LP 代币基本都是 fork Uniswap 的，所以 $r_0$和 $r_1$、$price_0$和 $price_1$ 都是能拿到的。 ​ 上面的公式我们其实可以看出，是通过市值反推价格，也没有什么巨大的逻辑问题。当我们需要访问其币价的时候已经可以满足需求。在 Web3.js 前端中，我们就可以照此拿到结果。 export const getLpTokenPrice = async ( lpAddress: string, lib: any, price0: BigNumber, price1: BigNumber ) =&gt; { const lpToken = getPancakeLp(lib, lpAddress); let [r0, r1] = (await lpToken.getReserves()).map((n) =&gt; bignumberToBN(n)); let totalSupply = bignumberToBN(await lpToken.totalSupply()); return r0 .multipliedBy(price0) .plus(r1.multipliedBy(price1)) .dividedBy(totalSupply); }; 至此，我的需求完成。 延时喂价漏洞 对于上文公式： ​ \[price_{lp}= \frac{r_0 \times price_0 + r_1 \times price_1}{totalSupply}\] 其实乍一看是不存在问题的。但是如果我们所做的需求，不仅仅是一个价格展示，而是一个借贷系统，用这种方式来获取清算系数，就会存在被闪电贷的风险。虽然 $price_0$和 $price_1$不能被操控，但是 $r_0$和 $r_1$是可以的。黑客可以通过操作 $r_0$ 和 $r_1$，从而对价格实现控制。 之前漫雾团队写过一篇「Warp Finance 被黑详解」的分析，采用了如下攻击流程： 通过 dydx 与 Uniswap 闪电贷借出 DAI 和 WETH； 用小部分 DAI 和 WETH 在 Uniswap 的 WETH-DAI LP 中添加流动性，获得 LP Token； 将 LP Token 抵押到 Wrap Finance 中； 用巨量的 WETH 兑换成 DAI，因为 WETH 迅速进入了 WETH-DAI 流动池，总数量大增。但是由于价格使用的是 Uniswap 的预言机，访问的是 Uniswap 的 LP 池，所以 WETH 的价格并未发生变化。从而导致 Wrap Finance 中的 WETH-DAI LP Token 价格迅速提高； 由于 LP Token 单价变高，导致黑客抵押的 LP Token 可以借出更多的稳定币来获息。 ​ 这里，我们发现漏洞的关键地方，其实是 $price$ 计算对于借贷项目中，使用的是他人的 LP 合约，还未等套利者来平衡价格，从而终究留出了时间差。 ​ 为了解决这个问题，如果我们可以找到一种方式，从而规避价格查询，就能大概率防止上述漏洞。这里，Alpha Finance 给出了另外一个推导公式。 获取公平 LP 价格方法 首先我们在一个 LP 池中，我们能保证的是恒定乘积 $K$ 值的大小，我们定义价格比值是 $P$，那么我们会有以下关系式： ​ \[\begin{cases} K=r_0 \times r_1 \\ P = \frac{r_1}{r_0} \end{cases}\] ​ 因为 $r_0$ 和 $r_1$ 在旧方法中是可以被操纵的，所以我们用 $K$ 和 $P$ 来反解真实的 $r’_{0}$ 和 $r’_1$ ： ​ \[\begin{cases} r'_0 = \sqrt{K / P} \\ r'_1 = \sqrt{K \times P} \end{cases}\] 如此，我们在带入一开始计算 $price_{lp}$的公式中： ​ \[\begin{align} price_{lp} &amp;= \frac{r'_0 \times price_0 + r'_1 \times price_1}{totalSupply} \\ &amp; = \frac{\sqrt{K/P}·price_0 + \sqrt{K·P}·price_1}{totalSupply} \\ &amp; = \frac{\sqrt{K · \frac{price_1}{price_0}·price_0^2} + \sqrt{K·\frac{price_0}{price_1}·price_1^2}}{totalSupply} \\ &amp; = \frac{2\sqrt{K·price_0·price_1}}{totalSupply} \\ &amp; = 2 \frac{\sqrt{r_0·r_1}·\sqrt{price_0 · price_1}}{totalSupply} \end{align}\] 我们可以发现，最终 Alpha Finance 给我们的推导式中，不会存在独立的 $r_0$ 和 $r_1$ ，取而代之的是它们的恒定乘积 $K$。 攻击可能性分析 使用以上公式，我们可以真正的避免攻击吗？ ​$price_0$和 $price_1$ 首先是可信源获取的正确价格，无法操纵； $totalSupply$ 只是改变了质押数量，其变化与质押的两个代币数量有关系； 对于 $r_0$ 和 $r_1$ ，在 Alpha Finance 的博客中提供了两种思路： 直接进行代币兑换（类似于上述攻击手段），由于 $r_0 \times r_1$ 是定值 $K$，所以无论如何变化都不会影响计算结果； 直接将 Token 打入 LP Token 合约地址中，由于 $r_0$ 和 $r_1$ 都是在二次根式下，所以付出 $x$ 倍的成果，最终只能获得 $\sqrt{x}$ 倍的收益，这显然是亏本的； 综上，在已知情况下，是可以有效避免攻击的。 总结 通过这次对 LP Token 价格计算的研究，并且对延时喂价漏洞的探求，了解了 LP 抵押使用一般方式计算带来的风险。计算价格的需求，一定要根据所做业务的类型，谨慎选择。 参考链接 Alpha Finance 关于获取公平 LP 价格的方法 一种安全的 LP 价格的获取方法曾汨 欢迎大家使用我个人研发的 Cakebot Finance 来体验去中心化 DAPP 挖矿。]]></summary></entry><entry><title type="html">Liquidity Providers 的数学原理</title><link href="https://www.desgard.com/2021/04/25/defi-lp-math.html" rel="alternate" type="text/html" title="Liquidity Providers 的数学原理" /><published>2021-04-25T00:00:00-08:00</published><updated>2021-04-25T00:00:00-08:00</updated><id>https://www.desgard.com/2021/04/25/defi-lp-math</id><content type="html" xml:base="https://www.desgard.com/2021/04/25/defi-lp-math.html"><![CDATA[<p>最近半年多一直在币圈玩 DeFi，这半年来增加了好多十分神奇的玩法，这都要得益于 Uniswap 的创新。</p>

<p>看了这么多 Up 主的视频，讲的都云里雾里的，其实就是简单的几个公式，这篇文章我们来从头推导一下无偿损失的公式，来计算一下<strong>为什么当单币种价格有强烈浮动的时候，为什么会有无偿损失</strong>。</p>

<h1 id="liquidity-providers-代币是什么">Liquidity Providers 代币是什么</h1>

<p>流动性提供者代币（Liquidity Providers Token），也就是我们经常说的 LP 代币，这是一个什么东西呢？</p>

<p>可以举一个最简单的例子，加入我们现在使用 BUSD 来购买 BNB，我们经常使用交易所的朋友们知道，交易所的挣钱模式是<strong>用户在交易时从交易金额中进行抽成来赚取手续费</strong>。</p>

<p>其实很多中心化交易所（CEX）看到了盈利模式中的用户激励机制，那就是你如果邀请别人试用我们的产品，那么<strong>交易所在进行手续费抽成的过程中，也会将其再次抽成，作为那些 KOL 的奖励</strong>。</p>

<p>而 Uniswap 这种去中心化交易所（DEX）就无法利用这种机制进行用户增长，因为所有的 DEX 没有用户注册机制，只需要连接用户的数字钱包即可完成交易。</p>

<p>于是，Uniswap 就设计了另外一种激励模式，<strong>AMM（Automated Market Maker） - 自动化做市商模型</strong>。关于自动化做市商这里我们不详细的去讲，我们只要了解以下几个动作代表了什么意思就可以（这里使用 BNB 和 BUSD 交易以及 PancakeSwap 平台为例）：</p>

<ol>
  <li><strong>用 BNB 和 BUSD 换取 BNB-BUSD LP 代币</strong>：相当于你为 BNB 和 BUSD 流动池增加了代币。并且你获得了 BNB ⇄ BUSD 这个交易中的对应代币份额的抽成奖励占比；
    <ol>
      <li>这里就体现了 DEX 通过换取流动性证明，从而完成了一种激励模式；</li>
      <li>PancakeSwap 在文档中提到，<strong>其 0.2% 的交易手续费当中，有 0.17% 的比例是提供给 LP 持有者的抽成奖励的</strong>。剩下的 0.03% 是平台的利润。具体规则可以查看<a href="https://docs.pancakeswap.finance/products/pancakeswap-exchange/trade">官方文档</a>。</li>
    </ol>
  </li>
  <li><strong>BNB-BUSD 代币挖矿</strong>：当我们拿到 BNB-BUSD LP Token 之后，我们可以继续放在 PancakeSwap 的 Farms 中进行挖矿（其年化 APR 如以下截图所示）。</li>
</ol>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/farms.png" alt="" /></p>

<p>所以，看到这里你应该也明白这个 LP Token 是个什么东西了。他其实就是你<strong>提供的流动性证明</strong>代币，<strong>持有这个代币你就可以获得对应币对在交易过程中手续费的抽成</strong>。</p>

<p>并且<strong>平台为了让你去填充代币池，通过质押 LP 代币挖矿的形式来吸引你去兑换，这样你也获得了收益，平台也获得了交易币对的深度池</strong>。</p>

<h1 id="无偿损失是如何来的">无偿损失是如何来的？</h1>

<p>有很多朋友应该是被 LP 代币挖矿的高收益吸引过来的。在一顿操作之后开始了挖矿，但是在 Remove LP 代币的时候，发现自己损失了好多 U。本来是来挖矿赚收益的，最后矿没挖多少，自己却亏了好多。这是怎么一回事呢？</p>

<p>这种情况就是我们所说的** IL 无偿损失（Impermanet Loss）<strong>，用来指</strong>在流动性代币价值与持有两种现货资产相比产生负收益的结果**。简单来说就是亏钱了！</p>

<p>为什么会产生无偿损失，我们以为 BNB 和 BUSD 提供流动性为例，来具体的描述一个场景。在例子之前我们需要了解以下变量：</p>

<h2 id="常数-kconstant-product">常数 K（Constant Product）</h2>

<p>常数 K 因子是用来为交易定价的一种方式，用这个常数来保证币对池子的价值平衡。
\(K = A \times B\)
这里面 \(A\)  和 \(B\)  是两个 Token 的数量。这里面我们用 BNB 和 BUSD 来举例子：</p>

<ul>
  <li>A - BNB 的数量</li>
  <li>B - BUSD 的数量</li>
</ul>

<p>A 和 B 带入到我们的例子中，后面用 \(C_{BNB}\) 和 \(C_{BUSD}\) 代替
\(K_{BNB-BUSD} = C_{BNB} \times C_{BUSD}\)</p>

<h2 id="定价-ptoken-price">定价 P（Token Price）</h2>

<p>这个是 Uniswap 中对于 LP 比对的一个条件，就是要保证当前配对时，币对中两个币的 U 本位价值相同。在这个例子中，我们引入 BNB 此时的价格 \(P_{BNB}\)  以及 BUSD 的价格 \(P_{BUSD}\)。此时我们可以得到等式：
\(P_{BNB} \times C_{BNB} = P_{BUSD} \times C_{BUSD}\)
由于我们的 BUSD 其实是和 $ 锚定的，那么其实 \(P_{BUSD} = 1\)，所以有以下式子：
\(P_{BNB} \times C_{BNB} = C_{BUSD}\)
\(P_{BNB} = \frac{C_{BUSD}}{C_{BNB}}\)</p>

<h2 id="数量公式">数量公式</h2>

<p>我们通过上述公式来推出两个代币的定价 P 的公式：</p>

\[\begin{cases}
C_{BNB} = \sqrt{\frac{K_{BNB-BUSD}}{P_{BNB}}} \\
C_{BUSD} = \sqrt{K_{BNB-BUSD} \times P_{BNB}}
\end{cases}\]

<p>如此，我们就可以通过常数 K 以及当前的币价来推导我们代币的数量了。接下来我们来看一个实际的场景，来直接感受一下无偿损失。</p>

<h2 id="实际场景">实际场景</h2>

<p>假如，我们在 <strong>1 BNB = 500 BUSD 的时候，组了一组 LP</strong> 。我们拿出了 20 个 BNB 和 10000 个 BUSD 进行 LP 流动性提供代币兑换。此时我们得到了这几个变量：</p>

\[\begin{cases}
P_{BNB} = 500 \\
P_{BUSD} = 1 \\
K = C_{BNB} \times C_{BUSD} = 2 \times 10^5
\end{cases}\]

<p>并且，我们保证此时的 K 也是后续所有情况下的常数 K，即组完 LP 代币后即时生效的常数。</p>

<p>过了 10 天，BNB 涨价了，<strong>当前价格为 1 BNB = 550 BUSD 了</strong>。随之我们的价格也变成了如下关系：</p>

\[\begin{cases}
P_{BNB} = 550 \\
P_{BUSD} = 1
\end{cases}\]

<p>我们带入到之前数量公式来计算此时 LP Token 等值的代币个数：</p>

\[\begin{split}

C'_{BNB} &amp;= \sqrt{\frac{K_{BNB-BUSD}}{P_{BNB}}} \\
&amp; = \sqrt{\frac{2 \times 10^5}{550}} \\
&amp; \approx 19.069 \ BNB\\
C'_{BUSD} &amp;= \sqrt{K_{BNB-BUSD} \times P_{BNB}}  \\
&amp; = \sqrt{2 \times 10^5 \times 550} \\
&amp; \approx 10488.09\ BUSD
\end{split}\]

<p>在 BNB 涨价到 550 BUSD 数量到时候，我们发现等值的 LP Token 兑换<strong>只能换回 19.069 个 BNB 和 10488.09 个 BUSD</strong>。如果我们来换算成 BUSD 作为单位来对比一下前后收益：</p>

<ul>
  <li>情况一：就是上述情况，我们持有来一定数量的 LP 代币，接触流动性后全部折算成 BUSD 可以得到以下结果：</li>
</ul>

\[\begin{split}

V_1 &amp; = 19.069 \times 550 + 10488.09 = 20976.04 \ BUSD

\end{split}\]

<ul>
  <li>情况二：如果我们持续持有 20 个 BNB 和 10000 个 BUSD，那么此时我们折算成 BUSD 可以得到以下结果：</li>
</ul>

<p>\(V_2 = 20 \times 550 + 10000 = 21000\ BUSD\)
<strong>经过以上分析，我们是可以看到如果我们持有 LP 代币不进行任何理财操作，其实我们组了 LP Token 后是会亏 \(21000 - 20976.04 = 23.96 \ BUSD\)的。</strong>
**</p>

<h1 id="相关补充">相关补充</h1>

<h2 id="lp-token-代币数量计算">LP Token 代币数量计算</h2>

<p>其实 LP Token 也是一种代币，它也拥有自己的合约地址。比如 Pancakeswap 上的 BNB-BUSD LP 代币合约地址 <code class="language-plaintext highlighter-rouge">0x58F876857a02D6762E0101bb5C46A8c1ED44Dc16</code> 。是代币肯定就有一个方式来计算数量，这里 Pancakeswap 和 Uniswap 的计算方式一样，采用以下公式：</p>

\[C_{BNB-BUSD\ LP} = \sqrt{C_{BNB}\times C_{BUSD}}\]

<p>所以，当我们用 20 个 BNB 和 10000 个 BUSD 兑换 LP 代币的时候，我们会获得大约 447.21 个 LP Token。</p>

<h2 id="简易的无偿损失表">简易的无偿损失表</h2>

<p>这个我下一篇文会具体的推演一下如何决策以及如何与收益来共同计算。这里先引用 <a href="https://pintail.medium.com/uniswap-a-good-deal-for-liquidity-providers-104c0b6816f2">「Uniswap: A Good Deal for Liquidity Providers?」</a>这篇文章中给出的结论：</p>

<ul>
  <li>a <strong>1.25x</strong> price change results in a <strong>0.6%</strong> loss relative to HODL</li>
  <li>a <strong>1.50x</strong> price change results in a <strong>2.0%</strong> loss relative to HODL</li>
  <li>a <strong>1.75x</strong> price change results in a <strong>3.8%</strong> loss relative to HODL</li>
  <li>a <strong>2x</strong> price change results in a <strong>5.7%</strong> loss relative to HODL</li>
  <li>a <strong>3x</strong> price change results in a <strong>13.4%</strong> loss relative to HODL</li>
  <li>a <strong>4x</strong> price change results in a <strong>20.0%</strong> loss relative to HODL</li>
  <li>a <strong>5x</strong> price change results in a <strong>25.5%</strong> loss relative to HODL</li>
</ul>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/lp_function_graph.png" alt="Losses/Price Change Function" /></p>

<h1 id="写在最后">写在最后</h1>

<p>DeFi 是一个金融游戏，如果你什么也不做研究并且什么也不去动手计算，那么永远都是韭菜。所以希望大家对于有趣的项目，先<strong>做好研究</strong>以及<strong>风险评估</strong>，在去玩耍。</p>

<blockquote>
  <p>欢迎大家使用我个人研发的 <a href="https://cakebot.finance/">Cakebot Finance</a> 来体验去中心化 DAPP 挖矿。</p>
</blockquote>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="Blockchain" /><category term="DeFi" /><summary type="html"><![CDATA[最近半年多一直在币圈玩 DeFi，这半年来增加了好多十分神奇的玩法，这都要得益于 Uniswap 的创新。 看了这么多 Up 主的视频，讲的都云里雾里的，其实就是简单的几个公式，这篇文章我们来从头推导一下无偿损失的公式，来计算一下为什么当单币种价格有强烈浮动的时候，为什么会有无偿损失。 Liquidity Providers 代币是什么 流动性提供者代币（Liquidity Providers Token），也就是我们经常说的 LP 代币，这是一个什么东西呢？ 可以举一个最简单的例子，加入我们现在使用 BUSD 来购买 BNB，我们经常使用交易所的朋友们知道，交易所的挣钱模式是用户在交易时从交易金额中进行抽成来赚取手续费。 其实很多中心化交易所（CEX）看到了盈利模式中的用户激励机制，那就是你如果邀请别人试用我们的产品，那么交易所在进行手续费抽成的过程中，也会将其再次抽成，作为那些 KOL 的奖励。 而 Uniswap 这种去中心化交易所（DEX）就无法利用这种机制进行用户增长，因为所有的 DEX 没有用户注册机制，只需要连接用户的数字钱包即可完成交易。 于是，Uniswap 就设计了另外一种激励模式，AMM（Automated Market Maker） - 自动化做市商模型。关于自动化做市商这里我们不详细的去讲，我们只要了解以下几个动作代表了什么意思就可以（这里使用 BNB 和 BUSD 交易以及 PancakeSwap 平台为例）： 用 BNB 和 BUSD 换取 BNB-BUSD LP 代币：相当于你为 BNB 和 BUSD 流动池增加了代币。并且你获得了 BNB ⇄ BUSD 这个交易中的对应代币份额的抽成奖励占比； 这里就体现了 DEX 通过换取流动性证明，从而完成了一种激励模式； PancakeSwap 在文档中提到，其 0.2% 的交易手续费当中，有 0.17% 的比例是提供给 LP 持有者的抽成奖励的。剩下的 0.03% 是平台的利润。具体规则可以查看官方文档。 BNB-BUSD 代币挖矿：当我们拿到 BNB-BUSD LP Token 之后，我们可以继续放在 PancakeSwap 的 Farms 中进行挖矿（其年化 APR 如以下截图所示）。 所以，看到这里你应该也明白这个 LP Token 是个什么东西了。他其实就是你提供的流动性证明代币，持有这个代币你就可以获得对应币对在交易过程中手续费的抽成。 并且平台为了让你去填充代币池，通过质押 LP 代币挖矿的形式来吸引你去兑换，这样你也获得了收益，平台也获得了交易币对的深度池。 无偿损失是如何来的？ 有很多朋友应该是被 LP 代币挖矿的高收益吸引过来的。在一顿操作之后开始了挖矿，但是在 Remove LP 代币的时候，发现自己损失了好多 U。本来是来挖矿赚收益的，最后矿没挖多少，自己却亏了好多。这是怎么一回事呢？ 这种情况就是我们所说的** IL 无偿损失（Impermanet Loss），用来指在流动性代币价值与持有两种现货资产相比产生负收益的结果**。简单来说就是亏钱了！ 为什么会产生无偿损失，我们以为 BNB 和 BUSD 提供流动性为例，来具体的描述一个场景。在例子之前我们需要了解以下变量： 常数 K（Constant Product） 常数 K 因子是用来为交易定价的一种方式，用这个常数来保证币对池子的价值平衡。 \(K = A \times B\) 这里面 \(A\)  和 \(B\)  是两个 Token 的数量。这里面我们用 BNB 和 BUSD 来举例子： A - BNB 的数量 B - BUSD 的数量 A 和 B 带入到我们的例子中，后面用 \(C_{BNB}\) 和 \(C_{BUSD}\) 代替 \(K_{BNB-BUSD} = C_{BNB} \times C_{BUSD}\) 定价 P（Token Price） 这个是 Uniswap 中对于 LP 比对的一个条件，就是要保证当前配对时，币对中两个币的 U 本位价值相同。在这个例子中，我们引入 BNB 此时的价格 \(P_{BNB}\)  以及 BUSD 的价格 \(P_{BUSD}\)。此时我们可以得到等式： \(P_{BNB} \times C_{BNB} = P_{BUSD} \times C_{BUSD}\) 由于我们的 BUSD 其实是和 $ 锚定的，那么其实 \(P_{BUSD} = 1\)，所以有以下式子： \(P_{BNB} \times C_{BNB} = C_{BUSD}\) \(P_{BNB} = \frac{C_{BUSD}}{C_{BNB}}\) 数量公式 我们通过上述公式来推出两个代币的定价 P 的公式： \[\begin{cases} C_{BNB} = \sqrt{\frac{K_{BNB-BUSD}}{P_{BNB}}} \\ C_{BUSD} = \sqrt{K_{BNB-BUSD} \times P_{BNB}} \end{cases}\] 如此，我们就可以通过常数 K 以及当前的币价来推导我们代币的数量了。接下来我们来看一个实际的场景，来直接感受一下无偿损失。 实际场景 假如，我们在 1 BNB = 500 BUSD 的时候，组了一组 LP 。我们拿出了 20 个 BNB 和 10000 个 BUSD 进行 LP 流动性提供代币兑换。此时我们得到了这几个变量： \[\begin{cases} P_{BNB} = 500 \\ P_{BUSD} = 1 \\ K = C_{BNB} \times C_{BUSD} = 2 \times 10^5 \end{cases}\] 并且，我们保证此时的 K 也是后续所有情况下的常数 K，即组完 LP 代币后即时生效的常数。 过了 10 天，BNB 涨价了，当前价格为 1 BNB = 550 BUSD 了。随之我们的价格也变成了如下关系： \[\begin{cases} P_{BNB} = 550 \\ P_{BUSD} = 1 \end{cases}\] 我们带入到之前数量公式来计算此时 LP Token 等值的代币个数： \[\begin{split} C'_{BNB} &amp;= \sqrt{\frac{K_{BNB-BUSD}}{P_{BNB}}} \\ &amp; = \sqrt{\frac{2 \times 10^5}{550}} \\ &amp; \approx 19.069 \ BNB\\ C'_{BUSD} &amp;= \sqrt{K_{BNB-BUSD} \times P_{BNB}} \\ &amp; = \sqrt{2 \times 10^5 \times 550} \\ &amp; \approx 10488.09\ BUSD \end{split}\] 在 BNB 涨价到 550 BUSD 数量到时候，我们发现等值的 LP Token 兑换只能换回 19.069 个 BNB 和 10488.09 个 BUSD。如果我们来换算成 BUSD 作为单位来对比一下前后收益： 情况一：就是上述情况，我们持有来一定数量的 LP 代币，接触流动性后全部折算成 BUSD 可以得到以下结果： \[\begin{split} V_1 &amp; = 19.069 \times 550 + 10488.09 = 20976.04 \ BUSD \end{split}\] 情况二：如果我们持续持有 20 个 BNB 和 10000 个 BUSD，那么此时我们折算成 BUSD 可以得到以下结果： \(V_2 = 20 \times 550 + 10000 = 21000\ BUSD\) 经过以上分析，我们是可以看到如果我们持有 LP 代币不进行任何理财操作，其实我们组了 LP Token 后是会亏 \(21000 - 20976.04 = 23.96 \ BUSD\)的。 ** 相关补充 LP Token 代币数量计算 其实 LP Token 也是一种代币，它也拥有自己的合约地址。比如 Pancakeswap 上的 BNB-BUSD LP 代币合约地址 0x58F876857a02D6762E0101bb5C46A8c1ED44Dc16 。是代币肯定就有一个方式来计算数量，这里 Pancakeswap 和 Uniswap 的计算方式一样，采用以下公式： \[C_{BNB-BUSD\ LP} = \sqrt{C_{BNB}\times C_{BUSD}}\] 所以，当我们用 20 个 BNB 和 10000 个 BUSD 兑换 LP 代币的时候，我们会获得大约 447.21 个 LP Token。 简易的无偿损失表 这个我下一篇文会具体的推演一下如何决策以及如何与收益来共同计算。这里先引用 「Uniswap: A Good Deal for Liquidity Providers?」这篇文章中给出的结论： a 1.25x price change results in a 0.6% loss relative to HODL a 1.50x price change results in a 2.0% loss relative to HODL a 1.75x price change results in a 3.8% loss relative to HODL a 2x price change results in a 5.7% loss relative to HODL a 3x price change results in a 13.4% loss relative to HODL a 4x price change results in a 20.0% loss relative to HODL a 5x price change results in a 25.5% loss relative to HODL 写在最后 DeFi 是一个金融游戏，如果你什么也不做研究并且什么也不去动手计算，那么永远都是韭菜。所以希望大家对于有趣的项目，先做好研究以及风险评估，在去玩耍。 欢迎大家使用我个人研发的 Cakebot Finance 来体验去中心化 DAPP 挖矿。]]></summary></entry><entry><title type="html">Podspec 管理策略</title><link href="https://www.desgard.com/2020/11/05/cocoapods-story-6.html" rel="alternate" type="text/html" title="Podspec 管理策略" /><published>2020-11-05T00:00:00-08:00</published><updated>2020-11-05T00:00:00-08:00</updated><id>https://www.desgard.com/2020/11/05/cocoapods-story-6</id><content type="html" xml:base="https://www.desgard.com/2020/11/05/cocoapods-story-6.html"><![CDATA[<h1 id="引子">引子</h1>

<p>本文是 Core 的最后一篇，它与另外两篇文章「Podfile 解析逻辑」和「PodSpec 文件分析」共同支撑起 CocoaPods 世界的骨架。CocoaPods-Core 这个库之所以被命名为 Core 就是因为它包含了 <strong>Podfile -&gt; Spec Repo -&gt; PodSpec</strong> 这条完整的链路，将散落各地的依赖库连接起来并基于此骨架不断地完善功能。</p>

<p>从提供各种便利的命令行工具，到依赖库与主项目的自动集成，再到提供多样的 Xcode 编译配置、单元测试、资源管理等等，最终形成了我们所见的 CocoaPods。</p>

<p>今天我们就来聊聊 <code class="language-plaintext highlighter-rouge">Spec Repo</code> 这个 <code class="language-plaintext highlighter-rouge">PodSpec</code> 的聚合仓库以及它的演变与问题。</p>

<h1 id="source">Source</h1>

<p>作为 <code class="language-plaintext highlighter-rouge">PodSpec</code> 的聚合仓库，Spec Repo <strong>记录着所有 <code class="language-plaintext highlighter-rouge">pod</code> 所发布的不同版本的 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件</strong>。该仓库对应到 Core 的数据结构为 <code class="language-plaintext highlighter-rouge">Source</code>，即为今天的主角。</p>

<p>整个 <code class="language-plaintext highlighter-rouge">Source</code> 的结构比较简单，它基本是围绕着 Git 来做文章，主要是对 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件进行各种查找更新操作。结构如下：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># 用于检查 spec 是否符合当前 Source 要求</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/source/acceptor'</span>
<span class="c1"># 记录本地 source 的集合</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/source/aggregate'</span>
<span class="c1"># 用于校验 source 的错误和警告</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/source/health_reporter'</span>
<span class="c1"># source 管理器</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/source/manager'</span>
<span class="c1"># source 元数据</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/source/metadata'</span>

<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Source</span>
    <span class="c1"># 仓库默认的 Git 分支</span>
    <span class="no">DEFAULT_SPECS_BRANCH</span> <span class="o">=</span> <span class="s1">'master'</span><span class="p">.</span><span class="nf">freeze</span>
    <span class="c1"># 记录仓库的元数据</span>
    <span class="nb">attr_reader</span> <span class="ss">:metadata</span>
    <span class="c1"># 记录仓库的本地地址</span>
    <span class="nb">attr_reader</span> <span class="ss">:repo</span>
    <span class="c1"># repo 仓库地址 ~/.cocoapods/repos/{repo_name}</span>
    <span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">repo</span><span class="p">)</span>
      <span class="vi">@repo</span> <span class="o">=</span> <span class="no">Pathname</span><span class="p">(</span><span class="n">repo</span><span class="p">).</span><span class="nf">expand_path</span>
      <span class="vi">@versions_by_name</span> <span class="o">=</span> <span class="p">{}</span>
      <span class="n">refresh_metadata</span>
    <span class="k">end</span>
    <span class="c1"># 读取 Git 仓库中的 remote url 或 .git 目录</span>
    <span class="k">def</span> <span class="nf">url</span>
      <span class="vi">@url</span> <span class="o">||=</span> <span class="k">begin</span>
        <span class="n">remote</span> <span class="o">=</span> <span class="n">repo_git</span><span class="p">(</span><span class="sx">%w(config --get remote.origin.url)</span><span class="p">)</span>
        <span class="k">if</span> <span class="o">!</span><span class="n">remote</span><span class="p">.</span><span class="nf">empty?</span>
          <span class="n">remote</span>
        <span class="k">elsif</span> <span class="p">(</span><span class="n">repo</span> <span class="o">+</span> <span class="s1">'.git'</span><span class="p">).</span><span class="nf">exist?</span>
          <span class="s2">"file://</span><span class="si">#{</span><span class="n">repo</span><span class="si">}</span><span class="s2">/.git"</span>
        <span class="k">end</span>
      <span class="k">end</span>
    <span class="k">end</span>

    <span class="k">def</span> <span class="nf">type</span>
      <span class="n">git?</span> <span class="p">?</span> <span class="s1">'git'</span> <span class="p">:</span> <span class="s1">'file system'</span>
    <span class="k">end</span>
    <span class="c1"># ...</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">Source</code> 还有两个子类 <strong>CDNSource</strong> 和 <strong>TrunkSource</strong>，TrunkSouce 是 CocoaPods 的默认仓库。在版本 1.7.2 之前 Master Repo 的 URL 指向为 Github 的 <a href="https://github.com/CocoaPods/Specs" title="Specs 仓库">Specs 仓库</a>，这也是造成我们每次 <code class="language-plaintext highlighter-rouge">pod install</code> 或 <code class="language-plaintext highlighter-rouge">pod update</code> 慢的原因之一。它不仅保存了近 10 年来 PodSpec 文件同时还包括 Git 记录，再加上墙的原因，每次更新都非常痛苦。而在 1.7.2 之后 CocoaPods 的默认 Source 终于改为了 CDN 指向，同时支持按需下载，缓解了 <code class="language-plaintext highlighter-rouge">pod</code> 更新和磁盘占用过大问题。</p>

<p><code class="language-plaintext highlighter-rouge">Source</code> 的依赖关系如下：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440065-dd4bafb0-c7c5-4048-baa1-ff03aca64e7b.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<p>回到 <code class="language-plaintext highlighter-rouge">Source</code> 来看其如何初始化的，可以看到其构造函数 <code class="language-plaintext highlighter-rouge">#initialize(repo)</code> 将传入的 repo 地址保存后，直接调用了 <code class="language-plaintext highlighter-rouge">#refresh_metadata</code> 来完成元数据的加载：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">refresh_metadata</span>
  <span class="vi">@metadata</span> <span class="o">=</span> <span class="no">Metadata</span><span class="p">.</span><span class="nf">from_file</span><span class="p">(</span><span class="n">metadata_path</span><span class="p">)</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">metadata_path</span>
  <span class="n">repo</span> <span class="o">+</span> <span class="s1">'CocoaPods-version.yml'</span>
<span class="k">end</span>
</code></pre></div></div>

<h2 id="metadata">Metadata</h2>

<p>Metadata 是保存在 repo 目录下，名为 <code class="language-plaintext highlighter-rouge">CocoaPods-version.yml</code> 的文件，<strong>用于记录该 Source 所支持的 CocoaPods 的版本以及仓库的分片规则</strong>。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">autoload</span> <span class="ss">:Digest</span><span class="p">,</span> <span class="s1">'digest/md5'</span>
<span class="nb">require</span> <span class="s1">'active_support/hash_with_indifferent_access'</span>
<span class="nb">require</span> <span class="s1">'active_support/core_ext/hash/indifferent_access'</span>

<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Source</span>
    <span class="k">class</span> <span class="nc">Metadata</span>
      <span class="c1"># 最低可支持的 CocoaPods 版本，对应字段 `min`</span>
      <span class="nb">attr_reader</span> <span class="ss">:minimum_cocoapods_version</span>
      <span class="c1"># 最高可支持的 CocoaPods 版本，对应字段 `max`</span>
      <span class="nb">attr_reader</span> <span class="ss">:maximum_cocoapods_version</span>
      <span class="c1"># 最新 CocoaPods 版本，对应字段 `last`</span>
      <span class="nb">attr_reader</span> <span class="ss">:latest_cocoapods_version</span>
      <span class="c1"># 规定截取的关键字段的前缀长度和数量</span>
      <span class="nb">attr_reader</span> <span class="ss">:prefix_lengths</span>
      <span class="c1"># 可兼容的 CocoaPods 最新版本</span>
      <span class="nb">attr_reader</span> <span class="ss">:last_compatible_versions</span>
      <span class="c1"># ...</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>这里以笔者 💻 环境中 Master 仓库下的 <code class="language-plaintext highlighter-rouge">CocoaPods-version.yml</code> 文件内容为例：</p>

<div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nn">---</span>
<span class="na">min</span><span class="pi">:</span> <span class="s">1.0.0</span>
<span class="na">last</span><span class="pi">:</span> <span class="s">1.10.0.beta.1</span>
<span class="na">prefix_lengths</span><span class="pi">:</span>
  <span class="pi">-</span> <span class="m">1</span>
  <span class="pi">-</span> <span class="m">1</span>
  <span class="pi">-</span> <span class="m">1</span>
</code></pre></div></div>

<p>最低支持版本为 <code class="language-plaintext highlighter-rouge">1.0.0</code>，最新可用版本为 <code class="language-plaintext highlighter-rouge">1.10.0.beta.1</code>，以及最后这个 <code class="language-plaintext highlighter-rouge">prefix_lengths</code> 为 <code class="language-plaintext highlighter-rouge">[1, 1, 1]</code> 的数组。那么这个 <strong>prefix_lengths 的作用是什么呢 ？</strong></p>

<p>要回答这个问题，我们先来看一张 <code class="language-plaintext highlighter-rouge">Spec Repo</code> 的目录结构图：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440138-7037ff08-7e58-4e02-bf7a-0cc4d10032a0.jpeg#align=left&amp;display=inline&amp;height=1168&amp;margin=%5Bobject%20Object%5D&amp;originHeight=1168&amp;originWidth=3390&amp;size=0&amp;status=done&amp;style=none&amp;width=3390" alt="" /></p>

<p>再 🤔 另外一个问题，<strong>为什么 CocoaPods 生成的目录结构是这样 ？</strong></p>

<p>其实在 2016 年 CocoaPods Spec 仓库下的所有文件都在同级目录，不像现在这样做了分片。这个是为了解决当时用户的吐槽：<a href="https://github.com/CocoaPods/CocoaPods/issues/4989#issuecomment-193772935" title="Github 下载慢">Github 下载慢</a>，最终解决方案的结果就如你所见：<strong>将 Git 仓库进行了分片</strong>。</p>

<p>那么问题来了，<strong>为什么分片能够提升 Github 下载速度？</strong></p>

<p>很重要的一点是 CocoaPods 的 <code class="language-plaintext highlighter-rouge">Spec Repo</code> 本质上是 Git 仓库，而 Git 在做变更管理的时候，会记录目录的变更，每个子目录都会对应一个 Git model。而当目录中的文件数量过多的时候，Git 要找出对应的变更就变得十分困难。有兴趣的同学可以查看<a href="https://blog.cocoapods.org/Master-Spec-Repo-Rate-Limiting-Post-Mortem/#too-many-directory-entries" title="官方说明">官方说明</a>。</p>

<p>另外再补充一点，在 Linux 中最经典的一句话是：「<strong>一切皆文件</strong>」，不仅普通的文件和目录，就连块设备、管道、socket 等，也都是统一交给文件系统管理的。也就是说就算不用 Git 来管理 Specs 仓库，当目录下存在数以万计的文件时，如何高效查找目标文件也是需要考虑的问题。</p>

<blockquote>
  <p>Tips：关于文件系统层次结构有兴趣的同学可以查看<a href="https://www.wikiwand.com/en/Filesystem_Hierarchy_Standard" title="FHS 标准">FHS 标准</a>，以及知乎这篇：<a href="https://zhuanlan.zhihu.com/p/183238194#tocbar--13f51dj" title="传送门">传送门</a></p>
</blockquote>

<p>回到 CocoaPods，如何对 Master 仓库目录进行分片就涉及到 metadata 类中的关键方法：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">path_fragment</span><span class="p">(</span><span class="n">pod_name</span><span class="p">,</span> <span class="n">version</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
  <span class="n">prefixes</span> <span class="o">=</span> <span class="k">if</span> <span class="n">prefix_lengths</span><span class="p">.</span><span class="nf">empty?</span>
               <span class="p">[]</span>
             <span class="k">else</span>
               <span class="n">hashed</span> <span class="o">=</span> <span class="no">Digest</span><span class="o">::</span><span class="no">MD5</span><span class="p">.</span><span class="nf">hexdigest</span><span class="p">(</span><span class="n">pod_name</span><span class="p">)</span>
               <span class="n">prefix_lengths</span><span class="p">.</span><span class="nf">map</span> <span class="k">do</span> <span class="o">|</span><span class="n">length</span><span class="o">|</span>
                 <span class="n">hashed</span><span class="p">.</span><span class="nf">slice!</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="n">length</span><span class="p">)</span>
               <span class="k">end</span>
             <span class="k">end</span>
  <span class="n">prefixes</span><span class="p">.</span><span class="nf">concat</span><span class="p">([</span><span class="n">pod_name</span><span class="p">,</span> <span class="n">version</span><span class="p">]).</span><span class="nf">compact</span>
<span class="k">end</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">#path_fragment</code> 会依据 pod_name 和 version 来生成 pod 对应的索引目录：</p>

<ol>
  <li>首先对 pod_name 进行 MD5 计算获取摘要；</li>
  <li>遍历 <code class="language-plaintext highlighter-rouge">prefix_lengths</code> 对生成的摘要不断截取指定的长度作为文件索引。</li>
</ol>

<p>以 <code class="language-plaintext highlighter-rouge">AFNetworking</code> 为例：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="err">$</span> <span class="no">Digest</span><span class="o">::</span><span class="no">MD5</span><span class="p">.</span><span class="nf">hexdigest</span><span class="p">(</span><span class="s1">'AFNetworking'</span><span class="p">)</span>
<span class="s2">"a75d452377f3996bdc4b623a5df25820"</span>
</code></pre></div></div>

<p>由于我们的 <code class="language-plaintext highlighter-rouge">prefix_lengths</code> 为 <code class="language-plaintext highlighter-rouge">[1, 1, 1]</code> 数组，那么它将会从左到右依次截取出一个字母，即： <code class="language-plaintext highlighter-rouge">a</code>、<code class="language-plaintext highlighter-rouge">7</code>、<code class="language-plaintext highlighter-rouge">5</code> ，这三个字母作为索引目录，它正好符合我们 👆 目录结构图中 AFNetworking 的所在位置。</p>

<h2 id="versions">Versions</h2>

<p>要找到 <code class="language-plaintext highlighter-rouge">Podfile</code> 中限定版本号范围的 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件还需要需要最后一步，获取当前已发布的 Versions 列表，并通过比较 Version 得出最终所需的 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件。</p>

<p>在上一步已通过 <code class="language-plaintext highlighter-rouge">metadata</code> 和 <code class="language-plaintext highlighter-rouge">pod_name</code> 计算出 <code class="language-plaintext highlighter-rouge">pod</code> 所在目录，接着就是找到 <code class="language-plaintext highlighter-rouge">pod</code> 目录下的 Versions 列表：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440134-53557a72-ffc0-4a65-bfc0-39a85635be71.jpeg#align=left&amp;display=inline&amp;height=948&amp;margin=%5Bobject%20Object%5D&amp;originHeight=948&amp;originWidth=2680&amp;size=0&amp;status=done&amp;style=none&amp;width=2680" alt="" /></p>

<p>获取 Versions：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">versions</span><span class="p">(</span><span class="nb">name</span><span class="p">)</span>
  <span class="k">return</span> <span class="kp">nil</span> <span class="k">unless</span> <span class="n">specs_dir</span>
  <span class="k">raise</span> <span class="no">ArgumentError</span><span class="p">,</span> <span class="s1">'No name'</span> <span class="k">unless</span> <span class="nb">name</span>
  <span class="n">pod_dir</span> <span class="o">=</span> <span class="n">pod_path</span><span class="p">(</span><span class="nb">name</span><span class="p">)</span>
  <span class="k">return</span> <span class="k">unless</span> <span class="n">pod_dir</span><span class="p">.</span><span class="nf">exist?</span>
  <span class="vi">@versions_by_name</span><span class="p">[</span><span class="nb">name</span><span class="p">]</span> <span class="o">||=</span> <span class="n">pod_dir</span><span class="p">.</span><span class="nf">children</span><span class="p">.</span><span class="nf">map</span> <span class="k">do</span> <span class="o">|</span><span class="n">v</span><span class="o">|</span>
    <span class="n">basename</span> <span class="o">=</span> <span class="n">v</span><span class="p">.</span><span class="nf">basename</span><span class="p">.</span><span class="nf">to_s</span>
    <span class="k">begin</span>
      <span class="no">Version</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">basename</span><span class="p">)</span> <span class="k">if</span> <span class="n">v</span><span class="p">.</span><span class="nf">directory?</span> <span class="o">&amp;&amp;</span> <span class="n">basename</span><span class="p">[</span><span class="mi">0</span><span class="p">,</span> <span class="mi">1</span><span class="p">]</span> <span class="o">!=</span> <span class="s1">'.'</span>
    <span class="k">rescue</span> <span class="no">ArgumentError</span>
    <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s1">'An unexpected version directory ...'</span>
    <span class="k">end</span>
  <span class="k">end</span><span class="p">.</span><span class="nf">compact</span><span class="p">.</span><span class="nf">sort</span><span class="p">.</span><span class="nf">reverse</span>
<span class="k">end</span>
</code></pre></div></div>

<p>该方法重点在于将 <code class="language-plaintext highlighter-rouge">pod_dir</code> 下的每个目录都转换成为了 <strong>Version</strong> 类型，并在最后进行了 sort 排序。</p>

<blockquote>
  <p><code class="language-plaintext highlighter-rouge">#versions</code> 方法主要在 <code class="language-plaintext highlighter-rouge">pod search</code> 命令中被调用，后续会介绍。</p>
</blockquote>

<p>来搂一眼 Version 类：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">Version</span> <span class="o">&lt;</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Vendor</span><span class="o">::</span><span class="no">Gem</span><span class="o">::</span><span class="no">Version</span>
  <span class="no">METADATA_PATTERN</span> <span class="o">=</span> <span class="s1">'(\+[0-9a-zA-Z\-\.]+)'</span>
  <span class="no">VERSION_PATTERN</span> <span class="o">=</span> <span class="s2">"[0-9]+(</span><span class="se">\\</span><span class="s2">.[0-9a-zA-Z</span><span class="se">\\</span><span class="s2">-]+)*</span><span class="si">#{</span><span class="no">METADATA_PATTERN</span><span class="si">}</span><span class="s2">?"</span>
  <span class="c1"># ...</span>
<span class="k">end</span>
</code></pre></div></div>

<p>该 Version 继承于 <a href="https://www.rubydoc.info/github/rubygems/rubygems/Gem/Version" title="Gem::Version">Gem::Version</a> 并对其进行了扩展，实现了语义化版本号的标准，sort 排序也是基于语义化的版本来比较的，这里我们稍微展开一下。</p>

<h3 id="semantic-versioning">Semantic Versioning</h3>

<p>语义化版本号（<a href="https://semver.org/" title="Semantic Versioning">Semantic Versioning</a> 简称：SemVer）绝对是依赖管理工具绕不开的坎。<strong>语义化的版本就是让版本号更具语义化，可以传达出关于软件本身的一些重要信息而不只是简单的一串数字。</strong> 我们每次对 Pod 依赖进行更新，最后最重要的一步就是更新正确的版本号，一旦发布出去，再要更改就比较麻烦了。</p>

<blockquote>
  <p><a href="https://github.com/semver/semver" title="SemVer">SemVer</a> 是由 Tom Preston-Werner 发起的一个关于软件版本号的命名规范，该作者为 Gravatars 创办者同时也是 GitHub 联合创始人。</p>
</blockquote>

<p>那什么是语义化版本号有什么特别呢 ？我们以 AFNetworking 的 <strong>release tag</strong> 示例：</p>

<div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>3.0.0
3.0.0-beta.1
3.0.0-beta.2
3.0.0-beta.3
3.0.1
</code></pre></div></div>

<p>这些 tags 并非随意递增的，它们背后正是遵循了语义化版本的标准。</p>

<p><strong>基本规则</strong></p>

<ul>
  <li>软件的版本通常由三位组成，如：X.Y.Z。</li>
  <li>版本是严格递增的，</li>
  <li>在发布重要版本时，可以发布 alpha, rc 等先行版本，</li>
  <li>alpha 和 rc 等修饰版本的关键字后面可以带上次数和 meta 信息，</li>
</ul>

<p><strong>版本格式：</strong></p>

<blockquote>
  <p>主版本号.次版本号.修订号</p>
</blockquote>

<p>版本号递增规则如下：</p>

<table>
  <thead>
    <tr>
      <th>Code status</th>
      <th>Stage</th>
      <th>Example version</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>新品首发</td>
      <td>从 1.0.0 开始</td>
      <td>1.0.0</td>
    </tr>
    <tr>
      <td>向后兼容的 BugFix</td>
      <td>增加补丁号 Z</td>
      <td>1.0.1</td>
    </tr>
    <tr>
      <td>向后兼容的 Feature</td>
      <td>增加次版本号 Y</td>
      <td>1.1.0</td>
    </tr>
    <tr>
      <td>向后不兼容的改动</td>
      <td>增加主版本号 X</td>
      <td>2.0.0</td>
    </tr>
    <tr>
      <td>重要版本的预览版</td>
      <td>补丁号后添加 alpha, rc</td>
      <td>2.1.0-rc.0</td>
    </tr>
  </tbody>
</table>

<p>关于 CocoaPods 的 Version 使用描述，<a href="https://guides.cocoapods.org/using/the-podfile.html#specifying-pod-versions" title="传送门">传送门</a>。</p>

<h2 id="cdnsource">CDNSource</h2>

<p>CocoaPods 在 1.7.2 版本正式将 Master 仓库托管到 Netlify 的 CDN 上，当时关于如何支持这一特性的文章和说明铺天盖地，这里还是推荐大家看<a href="https://blog.cocoapods.org/CocoaPods-1.7.2/" title="官方说明">官方说明</a>。另外，当时感受是似乎国内的部分 iOS 同学都炸了，各种标题党：<em>什么最完美的升级</em>等等。</p>

<p>所以这里明确一下，对于 CocoaPods 的 Master 仓库支持了 CDN 的行为，仅解决了两个问题：</p>

<ol>
  <li>利用 CDN 节点的全球化部署解决内容分发慢，提高 Specs 资源的下载速度。</li>
  <li>通过 Specs 按需下载摆脱了原有 Git Repo 模式下本地仓库的磁盘占用过大，操作卡的问题。</li>
</ol>

<p>然而，<strong>仅仅对 <code class="language-plaintext highlighter-rouge">PodSpec</code> 增加了 CDN 根本没能解决 GFW 导致的 Github 源码校验、更新、下载慢的问题。</strong> 只能说路漫漫其修远兮。</p>

<blockquote>
  <p>PS：作为 iOS 工程师，就经常被前端同学 😒 。你看这 CocoaPods 也太垃圾了吧！！！一旦删掉 <code class="language-plaintext highlighter-rouge">Pods</code> 目录重新 install 就卡半天，缓存基本不生效，哪像 npm 多快 balabala …</p>
</blockquote>

<p>先来看 CDNSource 结构：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">require</span> <span class="s1">'cocoapods-core/source'</span>
<span class="c1"># ...</span>
<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">CDNSource</span> <span class="o">&lt;</span> <span class="no">Source</span>
    <span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">repo</span><span class="p">)</span>
      <span class="c1"># 标记是否正在同步文件</span>
      <span class="vi">@check_existing_files_for_update</span> <span class="o">=</span> <span class="kp">false</span>
      <span class="c1"># 记录时间用于对比下载文件的新旧程度，以确认是否需要更新保存所下的资源</span>
      <span class="vi">@startup_time</span> <span class="o">=</span> <span class="no">Time</span><span class="p">.</span><span class="nf">new</span>
      <span class="c1"># 缓存查询过的 PodSpec 资源</span>
      <span class="vi">@version_arrays_by_fragment_by_name</span> <span class="o">=</span> <span class="p">{}</span>
      <span class="k">super</span><span class="p">(</span><span class="n">repo</span><span class="p">)</span>
    <span class="k">end</span>

    <span class="k">def</span> <span class="nf">url</span>
      <span class="vi">@url</span> <span class="o">||=</span> <span class="no">File</span><span class="p">.</span><span class="nf">read</span><span class="p">(</span><span class="n">repo</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s1">'.url'</span><span class="p">)).</span><span class="nf">chomp</span><span class="p">.</span><span class="nf">chomp</span><span class="p">(</span><span class="s1">'/'</span><span class="p">)</span> <span class="o">+</span> <span class="s1">'/'</span>
    <span class="k">end</span>

    <span class="k">def</span> <span class="nf">type</span>
      <span class="s1">'CDN'</span>
    <span class="k">end</span>
    <span class="c1"># ...</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>Source 类是基于 Github Repo 来同步更新 <code class="language-plaintext highlighter-rouge">PodSpec</code>，而 CDNSource 则是基于 CDN 服务所返回的 Response，因此将 Source 类的大部分方法重写了一个遍，具体会在 SourceManager 一节来展开。</p>

<p>最后看一下 <code class="language-plaintext highlighter-rouge">TrunkSource</code> 类：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">TrunkSource</span> <span class="o">&lt;</span> <span class="no">CDNSource</span>
    <span class="c1"># 新版落盘后仓库名称</span>
    <span class="no">TRUNK_REPO_NAME</span> <span class="o">=</span> <span class="s1">'trunk'</span><span class="p">.</span><span class="nf">freeze</span>

    <span class="no">TRUNK_REPO_URL</span> <span class="o">=</span> <span class="s1">'https://cdn.cocoapods.org/'</span><span class="p">.</span><span class="nf">freeze</span>

    <span class="k">def</span> <span class="nf">url</span>
      <span class="vi">@url</span> <span class="o">||=</span> <span class="no">TRUNK_REPO_URL</span>
      <span class="k">super</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>核心就是重写了返回的 <code class="language-plaintext highlighter-rouge">url</code>，由于旧版 Spec 仓库名称为 <code class="language-plaintext highlighter-rouge">master</code> 为了加以区分，CDN 仓库则改名为 <code class="language-plaintext highlighter-rouge">trunk</code>。</p>

<h1 id="source-manager">Source Manager</h1>

<p><code class="language-plaintext highlighter-rouge">Manager</code> 作为 source 的管理类，其主要任务为 source 的添加和获取，而对 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件的更新和查找行为则交由 source 各自实现。不过由于一个 <code class="language-plaintext highlighter-rouge">pod</code> 库可能对应多个不同的 source，这里又产生出 <code class="language-plaintext highlighter-rouge">Aggregate</code> 类来统一 <code class="language-plaintext highlighter-rouge">PodSpec</code> 的查询。</p>

<p>它们的关系如下：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440115-66b550de-dcf6-4449-9445-3af005eae414.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<p>Manager 实现：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Source</span>
    <span class="k">class</span> <span class="nc">Manager</span>
      <span class="nb">attr_reader</span> <span class="ss">:repos_dir</span>

      <span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">repos_dir</span><span class="p">)</span>
        <span class="vi">@repos_dir</span> <span class="o">=</span> <span class="no">Pathname</span><span class="p">(</span><span class="n">repos_dir</span><span class="p">).</span><span class="nf">expand_path</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">source_repos</span>
        <span class="k">return</span> <span class="p">[]</span> <span class="k">unless</span> <span class="n">repos_dir</span><span class="p">.</span><span class="nf">exist?</span>
        <span class="n">repos_dir</span><span class="p">.</span><span class="nf">children</span><span class="p">.</span><span class="nf">select</span><span class="p">(</span><span class="o">&amp;</span><span class="ss">:directory?</span><span class="p">).</span><span class="nf">sort_by</span> <span class="p">{</span> <span class="o">|</span><span class="n">d</span><span class="o">|</span> <span class="n">d</span><span class="p">.</span><span class="nf">basename</span><span class="p">.</span><span class="nf">to_s</span><span class="p">.</span><span class="nf">downcase</span> <span class="p">}</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">aggregate</span>
        <span class="n">aggregate_with_repos</span><span class="p">(</span><span class="n">source_repos</span><span class="p">)</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">aggregate_with_repos</span><span class="p">(</span><span class="n">repos</span><span class="p">)</span>
        <span class="n">sources</span> <span class="o">=</span> <span class="n">repos</span><span class="p">.</span><span class="nf">map</span> <span class="p">{</span> <span class="o">|</span><span class="n">path</span><span class="o">|</span> <span class="n">source_from_path</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="p">}</span>
        <span class="vi">@aggregates_by_repos</span> <span class="o">||=</span> <span class="p">{}</span>
        <span class="vi">@aggregates_by_repos</span><span class="p">[</span><span class="n">repos</span><span class="p">]</span> <span class="o">||=</span> <span class="no">Source</span><span class="o">::</span><span class="no">Aggregate</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">sources</span><span class="p">)</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">all</span>
        <span class="n">aggregate</span><span class="p">.</span><span class="nf">sources</span>
      <span class="k">end</span>
      <span class="c1"># ...</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>Manager 类的初始化仅需要传入当前 repos 目录，即 <code class="language-plaintext highlighter-rouge">~/.cocoapods/repos</code>，而 Aggregate 的生成则保存 <code class="language-plaintext highlighter-rouge">repos_dir</code> 了目录下的 Source，用于后续处理。</p>

<p>先看 Source 的生成，在 <code class="language-plaintext highlighter-rouge">#source_from_path</code> 中：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">source_from_path</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
  <span class="vi">@sources_by_path</span> <span class="o">||=</span> <span class="no">Hash</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="nb">hash</span><span class="p">,</span> <span class="n">key</span><span class="o">|</span>
    <span class="nb">hash</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="k">case</span>
                <span class="k">when</span> <span class="n">key</span><span class="p">.</span><span class="nf">basename</span><span class="p">.</span><span class="nf">to_s</span> <span class="o">==</span> <span class="no">Pod</span><span class="o">::</span><span class="no">TrunkSource</span><span class="o">::</span><span class="no">TRUNK_REPO_NAME</span>
                  <span class="no">TrunkSource</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
                <span class="k">when</span> <span class="p">(</span><span class="n">key</span> <span class="o">+</span> <span class="s1">'.url'</span><span class="p">).</span><span class="nf">exist?</span>
                  <span class="no">CDNSource</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
                <span class="k">else</span>
                  <span class="no">Source</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
                <span class="k">end</span>
  <span class="k">end</span>
  <span class="vi">@sources_by_path</span><span class="p">[</span><span class="n">path</span><span class="p">]</span>
<span class="k">end</span>
</code></pre></div></div>

<p>以 <code class="language-plaintext highlighter-rouge">repos_dir</code> 下的目录名称来区分类型，而 CDNSource 则需要确保其目录下存在名为 <code class="language-plaintext highlighter-rouge">.url</code> 的文件。同时会对生成的 source 进行缓存。</p>

<p>最后看 Aggregate 结构，核心就两个 search 方法：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Source</span>
    <span class="k">class</span> <span class="nc">Aggregate</span>
      <span class="nb">attr_reader</span> <span class="ss">:sources</span>

      <span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">sources</span><span class="p">)</span>
        <span class="k">raise</span> <span class="s2">"Cannot initialize an aggregate with a nil source: (</span><span class="si">#{</span><span class="n">sources</span><span class="si">}</span><span class="s2">)"</span> <span class="k">if</span> <span class="n">sources</span><span class="p">.</span><span class="nf">include?</span><span class="p">(</span><span class="kp">nil</span><span class="p">)</span>
        <span class="vi">@sources</span> <span class="o">=</span> <span class="n">sources</span>
      <span class="k">end</span>
      <span class="c1"># 查询依赖对应的 specs</span>
      <span class="k">def</span> <span class="nf">search</span><span class="p">(</span><span class="n">dependency</span><span class="p">)</span> <span class="o">...</span> <span class="k">end</span>

      <span class="c1"># 查询某个 pod 以发布的 specs</span>
      <span class="k">def</span> <span class="nf">search_by_name</span><span class="p">(</span><span class="n">query</span><span class="p">,</span> <span class="n">full_text_search</span> <span class="o">=</span> <span class="kp">false</span><span class="p">)</span> <span class="o">...</span> <span class="k">end</span>

      <span class="c1"># ...</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<h2 id="source-源起">Source 源起</h2>

<p>本节我们来谈谈 source 是如何添加到 <code class="language-plaintext highlighter-rouge">repo_dir</code> 目录下的。</p>

<p>由前面的介绍可知，每个 source 中自带 <strong>url</strong>，在 Source 类中 url 读取自 Git 仓库的 <code class="language-plaintext highlighter-rouge">remote.origin.url</code> 或本地 <code class="language-plaintext highlighter-rouge">.git</code> 目录，而在 CDNSource 中 url 则是读取自当前目录下的  <code class="language-plaintext highlighter-rouge">.url</code> 文件所保存的 URL 地址。</p>

<p>那 CDNSource 的  <strong><code class="language-plaintext highlighter-rouge">.url</code> 文件是在什么时候被写入的呢 ？</strong></p>

<p>这需要从 <code class="language-plaintext highlighter-rouge">Podfile</code> 说起。很多老项目的 <code class="language-plaintext highlighter-rouge">Podfile</code> 开头部分大都会有一行或多行 source 命令：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">source</span> <span class="s1">'https://github.com/CocoaPods/Specs.git'</span>
<span class="n">source</span> <span class="s1">'https://github.com/artsy/Specs.git'</span>
</code></pre></div></div>

<p>用于指定项目中 <code class="language-plaintext highlighter-rouge">PodSpec</code> 的查找源，这些指定源最终会保存在 <code class="language-plaintext highlighter-rouge">~/.cocoapods/repos</code> 目录下的仓库。</p>

<p>当敲下 <code class="language-plaintext highlighter-rouge">pod install</code> 命令后，在 <code class="language-plaintext highlighter-rouge">#resolve_dependencies</code> 阶段的依赖分析中将同时完成 sources 的初始化。</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440199-179380b9-7d18-43cf-a179-70c0945fbbfa.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods/installer/analyzer.rb</span>

<span class="k">def</span> <span class="nf">sources</span>
  <span class="vi">@sources</span> <span class="o">||=</span> <span class="k">begin</span>
    <span class="c1"># 省略获取 podfile、plugins、dependencies 的 source url ...</span>
    <span class="n">sources</span> <span class="o">=</span> <span class="o">...</span>

    <span class="n">result</span> <span class="o">=</span> <span class="n">sources</span><span class="p">.</span><span class="nf">uniq</span><span class="p">.</span><span class="nf">map</span> <span class="k">do</span> <span class="o">|</span><span class="n">source_url</span><span class="o">|</span>
      <span class="n">sources_manager</span><span class="p">.</span><span class="nf">find_or_create_source_with_url</span><span class="p">(</span><span class="n">source_url</span><span class="p">)</span>
    <span class="k">end</span>
    <span class="k">unless</span> <span class="n">plugin_sources</span><span class="p">.</span><span class="nf">empty?</span>
      <span class="n">result</span><span class="p">.</span><span class="nf">insert</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="o">*</span><span class="n">plugin_sources</span><span class="p">)</span>
      <span class="n">plugin_sources</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">source</span><span class="o">|</span>
        <span class="n">sources_manager</span><span class="p">.</span><span class="nf">add_source</span><span class="p">(</span><span class="n">source</span><span class="p">)</span>
      <span class="k">end</span>
    <span class="k">end</span>
    <span class="n">result</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>获取 sources url 之后会通过 <code class="language-plaintext highlighter-rouge">sources_manager</code> 来完成 source 更新，逻辑在 CocoaPods 项目的 Manager 扩展中：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods/sources_manager.rb</span>

<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Source</span>
    <span class="k">class</span> <span class="nc">Manager</span>

      <span class="k">def</span> <span class="nf">find_or_create_source_with_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
        <span class="n">source_with_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span> <span class="o">||</span> <span class="n">create_source_with_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">create_source_with_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
        <span class="nb">name</span> <span class="o">=</span> <span class="n">name_for_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
        <span class="n">is_cdn</span> <span class="o">=</span> <span class="n">cdn_url?</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
		  <span class="c1"># ...</span>
        <span class="k">begin</span>
          <span class="k">if</span> <span class="n">is_cdn</span>
            <span class="no">Command</span><span class="o">::</span><span class="no">Repo</span><span class="o">::</span><span class="no">AddCDN</span><span class="p">.</span><span class="nf">parse</span><span class="p">([</span><span class="nb">name</span><span class="p">,</span> <span class="n">url</span><span class="p">]).</span><span class="nf">run</span>
          <span class="k">else</span>
            <span class="no">Command</span><span class="o">::</span><span class="no">Repo</span><span class="o">::</span><span class="no">Add</span><span class="p">.</span><span class="nf">parse</span><span class="p">([</span><span class="nb">name</span><span class="p">,</span> <span class="n">url</span><span class="p">]).</span><span class="nf">run</span>
          <span class="k">end</span>
        <span class="k">rescue</span> <span class="no">Informative</span> <span class="o">=&gt;</span> <span class="n">e</span>
          <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="c1"># ...</span>
        <span class="k">ensure</span>
          <span class="no">UI</span><span class="p">.</span><span class="nf">title_level</span> <span class="o">=</span> <span class="n">previous_title_level</span>
        <span class="k">end</span>
        <span class="n">source</span> <span class="o">=</span> <span class="n">source_with_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
        <span class="k">raise</span> <span class="s2">"Unable to create a source with URL </span><span class="si">#{</span><span class="n">url</span><span class="si">}</span><span class="s2">"</span> <span class="k">unless</span> <span class="n">source</span>
        <span class="n">source</span>
      <span class="k">end</span>
      <span class="c1"># ...</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>查找会先调用 <code class="language-plaintext highlighter-rouge">#source_with_url</code> 进行缓存查询，如未命中则会先下载 Source 仓库，结束后重刷 aggreate 以更新 source。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods-core/source/manager.rb</span>

<span class="k">def</span> <span class="nf">source_with_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
  <span class="n">url</span> <span class="o">=</span> <span class="n">canonic_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
  <span class="n">url</span> <span class="o">=</span> <span class="s1">'https://github.com/cocoapods/specs'</span> <span class="k">if</span> <span class="n">url</span> <span class="o">=~</span> <span class="sr">%r{github.com[:/]+cocoapods/specs}</span>
  <span class="n">all</span><span class="p">.</span><span class="nf">find</span> <span class="k">do</span> <span class="o">|</span><span class="n">source</span><span class="o">|</span>
    <span class="n">source</span><span class="p">.</span><span class="nf">url</span> <span class="o">&amp;&amp;</span> <span class="n">canonic_url</span><span class="p">(</span><span class="n">source</span><span class="p">.</span><span class="nf">url</span><span class="p">)</span> <span class="o">==</span> <span class="n">url</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">canonic_url</span><span class="p">(</span><span class="n">url</span><span class="p">)</span>
  <span class="n">url</span><span class="p">.</span><span class="nf">downcase</span><span class="p">.</span><span class="nf">gsub</span><span class="p">(</span><span class="sr">/\.git$/</span><span class="p">,</span> <span class="s1">''</span><span class="p">).</span><span class="nf">gsub</span><span class="p">(</span><span class="sr">%r{</span><span class="se">\/</span><span class="sr">$}</span><span class="p">,</span> <span class="s1">''</span><span class="p">)</span>
<span class="k">end</span>
</code></pre></div></div>

<p>另外，仓库的下载的则会通过 <code class="language-plaintext highlighter-rouge">#cdn_url?</code> 方法区分，最后的下载则 📦 在两个命令类中，概括如下：</p>

<ul>
  <li><strong>Repo::AddCDN</strong>：即  <code class="language-plaintext highlighter-rouge">pod repo add-cdn</code> 命令，仅有的操作是将 url 写入 <code class="language-plaintext highlighter-rouge">.url</code> 文件中。</li>
  <li><strong>Repo::Add</strong>：即 <code class="language-plaintext highlighter-rouge">pod repo add</code> 命令，对于普通类型的 Source 仓库下载本质就是 <code class="language-plaintext highlighter-rouge">git clone</code> 操作。</li>
</ul>

<p>简化后源的添加流程如下：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440106-f3bf8e93-1ee1-4b35-9f61-43afad2d62ea.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<h2 id="podspec-查询">PodSpec 查询</h2>

<p>同样在 <code class="language-plaintext highlighter-rouge">#resolve_dependencies</code> 的依赖仲裁阶段，当 <strong>Molinillo</strong> 依赖仲裁开始前，会触发缓存查询 <code class="language-plaintext highlighter-rouge">#find_cached_set</code> 并最终调用到 Aggregate 的 <code class="language-plaintext highlighter-rouge">#search</code>。完整调用栈放在 <a href="https://gist.github.com/looseyi/492b220ea7e933e972b65876e491886f" title="gist">gist</a> 上。</p>

<p>我们来看看 <code class="language-plaintext highlighter-rouge">#search</code> 入口：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods-core/source/aggregate.rb</span>

<span class="k">def</span> <span class="nf">search</span><span class="p">(</span><span class="n">dependency</span><span class="p">)</span>
  <span class="n">found_sources</span> <span class="o">=</span> <span class="n">sources</span><span class="p">.</span><span class="nf">select</span> <span class="p">{</span> <span class="o">|</span><span class="n">s</span><span class="o">|</span> <span class="n">s</span><span class="p">.</span><span class="nf">search</span><span class="p">(</span><span class="n">dependency</span><span class="p">)</span> <span class="p">}</span>
  <span class="k">unless</span> <span class="n">found_sources</span><span class="p">.</span><span class="nf">empty?</span>
    <span class="no">Specification</span><span class="o">::</span><span class="no">Set</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">dependency</span><span class="p">.</span><span class="nf">root_name</span><span class="p">,</span> <span class="n">found_sources</span><span class="p">)</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>Aggregate 先遍历当前 sources 并进行 dependency 查找。由于 Git 仓库保存了完整的 PodSpecs，只要能在分片目录下查询到对应文件即可，最终结果会塞入 <code class="language-plaintext highlighter-rouge">Specification::Set</code> 返回。</p>

<blockquote>
  <p>Specification::Set 记录了当前 pod 关联的 Source，一个 pod 可能存在与多个不同的 Spec 仓库 中。</p>
</blockquote>

<h3 id="cdn-仓库查询">CDN 仓库查询</h3>

<p>CDNSource 重写了 <code class="language-plaintext highlighter-rouge">#search</code> 实现：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods-core/cdn_source.rb</span>

<span class="k">def</span> <span class="nf">search</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>
  <span class="k">unless</span> <span class="n">specs_dir</span>
    <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"Unable to find a source named: `</span><span class="si">#{</span><span class="nb">name</span><span class="si">}</span><span class="s2">`"</span>
  <span class="k">end</span>
  <span class="k">if</span> <span class="n">query</span><span class="p">.</span><span class="nf">is_a?</span><span class="p">(</span><span class="no">Dependency</span><span class="p">)</span>
    <span class="n">query</span> <span class="o">=</span> <span class="n">query</span><span class="p">.</span><span class="nf">root_name</span>
  <span class="k">end</span>

  <span class="n">fragment</span> <span class="o">=</span> <span class="n">pod_shard_fragment</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>
  <span class="n">ensure_versions_file_loaded</span><span class="p">(</span><span class="n">fragment</span><span class="p">)</span>
  <span class="n">version_arrays_by_name</span> <span class="o">=</span> <span class="vi">@version_arrays_by_fragment_by_name</span><span class="p">[</span><span class="n">fragment</span><span class="p">]</span> <span class="o">||</span> <span class="p">{}</span>

  <span class="n">found</span> <span class="o">=</span> <span class="n">version_arrays_by_name</span><span class="p">[</span><span class="n">query</span><span class="p">].</span><span class="nf">nil?</span> <span class="p">?</span> <span class="kp">nil</span> <span class="p">:</span> <span class="n">query</span>

  <span class="k">if</span> <span class="n">found</span>
    <span class="n">set</span> <span class="o">=</span> <span class="n">set</span><span class="p">(</span><span class="n">query</span><span class="p">)</span>
    <span class="n">set</span> <span class="k">if</span> <span class="n">set</span><span class="p">.</span><span class="nf">specification_name</span> <span class="o">==</span> <span class="n">query</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>逻辑两步走：</p>

<ol>
  <li>通过 <code class="language-plaintext highlighter-rouge">#ensure_versions_file_loaded</code> 检查 all_pods_versions 文件，如果不存在会进行下载操作。</li>
  <li>如果当前 source 包含查询的 pod，会创建 <code class="language-plaintext highlighter-rouge">Specification::Set</code> 作为查询结果，并在 <code class="language-plaintext highlighter-rouge">#specification_name</code> 方法内完成 <code class="language-plaintext highlighter-rouge">PodSpec</code> 的检查和下载。</li>
</ol>

<h4 id="1-all_pods_versions-文件下载">1. all_pods_versions 文件下载</h4>

<p>依据前面提到的分片规则会将 pod 名称 MD5 分割后拼成 URL。</p>

<p>以 <code class="language-plaintext highlighter-rouge">AFNetworking</code> 为例，经 <code class="language-plaintext highlighter-rouge">#pod_shard_fragment</code> 分割后获取的 fragment 为 <code class="language-plaintext highlighter-rouge">[a, 7, 5]</code>，则拼接后的 URL 为 <code class="language-plaintext highlighter-rouge">https://cdn.cocoapods.org/all_pods_versions_a_7_5.txt</code>，下载后的内容大致如下：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>AFNetworking/0.10.0/0.10.1/.../4.0.1
AppseeAnalytics/2.4.7/2.4.8/2.4.8.0/...
DynamsoftBarcodeReader/7.1.0/...
...
</code></pre></div></div>

<p>所包含的这些 pod 都是分片后得到的相同的地址，因此会保存在同一份 <code class="language-plaintext highlighter-rouge">all_pods_versions</code> 中。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">ensure_versions_file_loaded</span><span class="p">(</span><span class="n">fragment</span><span class="p">)</span>
  <span class="k">return</span> <span class="k">if</span> <span class="o">!</span><span class="vi">@version_arrays_by_fragment_by_name</span><span class="p">[</span><span class="n">fragment</span><span class="p">].</span><span class="nf">nil?</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="vi">@check_existing_files_for_update</span>

  <span class="n">index_file_name</span> <span class="o">=</span> <span class="n">index_file_name_for_fragment</span><span class="p">(</span><span class="n">fragment</span><span class="p">)</span>
  <span class="n">download_file</span><span class="p">(</span><span class="n">index_file_name</span><span class="p">)</span>
  <span class="n">versions_raw</span> <span class="o">=</span> <span class="n">local_file</span><span class="p">(</span><span class="n">index_file_name</span><span class="p">,</span> <span class="o">&amp;</span><span class="ss">:to_a</span><span class="p">).</span><span class="nf">map</span><span class="p">(</span><span class="o">&amp;</span><span class="ss">:chomp</span><span class="p">)</span>
  <span class="vi">@version_arrays_by_fragment_by_name</span><span class="p">[</span><span class="n">fragment</span><span class="p">]</span> <span class="o">=</span> <span class="n">versions_raw</span><span class="p">.</span><span class="nf">reduce</span><span class="p">({})</span> <span class="k">do</span> <span class="o">|</span><span class="nb">hash</span><span class="p">,</span> <span class="n">row</span><span class="o">|</span>
    <span class="n">row</span> <span class="o">=</span> <span class="n">row</span><span class="p">.</span><span class="nf">split</span><span class="p">(</span><span class="s1">'/'</span><span class="p">)</span>
    <span class="n">pod</span> <span class="o">=</span> <span class="n">row</span><span class="p">.</span><span class="nf">shift</span>
    <span class="n">versions</span> <span class="o">=</span> <span class="n">row</span>

    <span class="nb">hash</span><span class="p">[</span><span class="n">pod</span><span class="p">]</span> <span class="o">=</span> <span class="n">versions</span>
    <span class="nb">hash</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">index_file_name_for_fragment</span><span class="p">(</span><span class="n">fragment</span><span class="p">)</span>
  <span class="n">fragment_joined</span> <span class="o">=</span> <span class="n">fragment</span><span class="p">.</span><span class="nf">join</span><span class="p">(</span><span class="s1">'_'</span><span class="p">)</span>
  <span class="n">fragment_joined</span> <span class="o">=</span> <span class="s1">'_'</span> <span class="o">+</span> <span class="n">fragment_joined</span> <span class="k">unless</span> <span class="n">fragment</span><span class="p">.</span><span class="nf">empty?</span>
  <span class="s2">"all_pods_versions</span><span class="si">#{</span><span class="n">fragment_joined</span><span class="si">}</span><span class="s2">.txt"</span>
<span class="k">end</span>
</code></pre></div></div>

<p>另外每一份 pods_version 都会对应生成一个文件用于保存 ETag，具体会在下一节会介绍。</p>

<h4 id="2-podspec-文件下载">2. PodSpec 文件下载</h4>

<p><code class="language-plaintext highlighter-rouge">#specification_name</code> 将从 <code class="language-plaintext highlighter-rouge">all_pods_versions</code> 索引文件中找出该 pod 所发布的版本号，依次检查下载对应版本的 <code class="language-plaintext highlighter-rouge">PodSpec.json</code> 文件。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Specification</span>
    <span class="k">class</span> <span class="nc">Set</span>
      <span class="nb">attr_reader</span> <span class="ss">:name</span>
      <span class="nb">attr_reader</span> <span class="ss">:sources</span>

      <span class="k">def</span> <span class="nf">specification_name</span>
        <span class="n">versions_by_source</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">source</span><span class="p">,</span> <span class="n">versions</span><span class="o">|</span>
          <span class="k">next</span> <span class="k">unless</span> <span class="n">version</span> <span class="o">=</span> <span class="n">versions</span><span class="p">.</span><span class="nf">first</span>
          <span class="k">return</span> <span class="n">source</span><span class="p">.</span><span class="nf">specification</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">version</span><span class="p">).</span><span class="nf">name</span>
        <span class="k">end</span>
        <span class="kp">nil</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">versions_by_source</span>
        <span class="vi">@versions_by_source</span> <span class="o">||=</span> <span class="n">sources</span><span class="p">.</span><span class="nf">each_with_object</span><span class="p">({})</span> <span class="k">do</span> <span class="o">|</span><span class="n">source</span><span class="p">,</span> <span class="n">result</span><span class="o">|</span>
          <span class="n">result</span><span class="p">[</span><span class="n">source</span><span class="p">]</span> <span class="o">=</span> <span class="n">source</span><span class="p">.</span><span class="nf">versions</span><span class="p">(</span><span class="nb">name</span><span class="p">)</span>
        <span class="k">end</span>
      <span class="k">end</span>
      <span class="c1"># ...</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>绕了一圈后回到 Source 的 <code class="language-plaintext highlighter-rouge">#versions</code> 方法，由于 CDN Source 不会全量下载 pod 的 PodSpec 文件，在 <a href="https://www.rubydoc.info/gems/cocoapods-core/Pod/CDNSource#versions-instance_method" title="**#version**"><strong>#version</strong></a> 的检查过程会进行下载操作。</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440097-d2c42b93-84f0-4655-8070-e53ef66ccf90.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<h3 id="pod-search-查询命令">Pod Search 查询命令</h3>

<p>CocoaPods 还提供了命令行工具 <code class="language-plaintext highlighter-rouge">cocoapods-search</code> 用于已发布的 <code class="language-plaintext highlighter-rouge">PodSpec</code> 查找：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>pod search <span class="sb">`</span>QUERY<span class="sb">`</span>
</code></pre></div></div>

<p>它提供了 Web 查询和本地查询。本地查询则不同于 <code class="language-plaintext highlighter-rouge">#search</code>，它需要调用 Aggregate 的 <code class="language-plaintext highlighter-rouge">#search_by_name</code> ，其实现同 <code class="language-plaintext highlighter-rouge">#search</code> 类似，最终也会走到 Source 的 <a href="https://www.rubydoc.info/gems/cocoapods-core/Pod/Source/Aggregate#search_by_name-instance_method" title="#versions">#versions</a> 方法。</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440110-76906470-4ec9-40fb-957b-ccbf157b45e3.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<blockquote>
  <p>注意，Gti 仓库的 <code class="language-plaintext highlighter-rouge">#search_by_name</code> 查询仍旧为文件查找，不会调用其 <code class="language-plaintext highlighter-rouge">#versions</code> 方法。</p>
</blockquote>

<h2 id="repo-更新">Repo 更新</h2>

<p><code class="language-plaintext highlighter-rouge">pod install</code> 执行过程如果带上了 <code class="language-plaintext highlighter-rouge">--repo-update</code> 命令则在 <code class="language-plaintext highlighter-rouge">#resolve_dependencies</code> 阶段会触发 <code class="language-plaintext highlighter-rouge">#update_repositories</code> 更新 Spec 仓库：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods/installer/analyzer.rb</span>

<span class="k">def</span> <span class="nf">update_repositories</span>
  <span class="n">sources</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">source</span><span class="o">|</span>
    <span class="k">if</span> <span class="n">source</span><span class="p">.</span><span class="nf">updateable?</span>
      <span class="n">sources_manager</span><span class="p">.</span><span class="nf">update</span><span class="p">(</span><span class="n">source</span><span class="p">.</span><span class="nf">name</span><span class="p">,</span> <span class="kp">true</span><span class="p">)</span>
    <span class="k">else</span>
      <span class="no">UI</span><span class="p">.</span><span class="nf">message</span> <span class="s2">"Skipping ..."</span>
    <span class="k">end</span>
  <span class="k">end</span>
  <span class="vi">@specs_updated</span> <span class="o">=</span> <span class="kp">true</span>
<span class="k">end</span>
</code></pre></div></div>

<p>不过 <code class="language-plaintext highlighter-rouge">#update</code> 的实现逻辑在 CocoaPods 项目的 Manager 扩展中：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods/sources_managers.rb</span>

<span class="k">def</span> <span class="nf">update</span><span class="p">(</span><span class="n">source_name</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">,</span> <span class="n">show_output</span> <span class="o">=</span> <span class="kp">false</span><span class="p">)</span>
  <span class="k">if</span> <span class="n">source_name</span>
    <span class="n">sources</span> <span class="o">=</span> <span class="p">[</span><span class="n">updateable_source_named</span><span class="p">(</span><span class="n">source_name</span><span class="p">)]</span>
  <span class="k">else</span>
    <span class="n">sources</span> <span class="o">=</span> <span class="n">updateable_sources</span>
  <span class="k">end</span>

  <span class="n">changed_spec_paths</span> <span class="o">=</span> <span class="p">{}</span>

  <span class="c1"># Do not perform an update if the repos dir has not been setup yet.</span>
  <span class="k">return</span> <span class="k">unless</span> <span class="n">repos_dir</span><span class="p">.</span><span class="nf">exist?</span>

  <span class="no">File</span><span class="p">.</span><span class="nf">open</span><span class="p">(</span><span class="s2">"</span><span class="si">#{</span><span class="n">repos_dir</span><span class="si">}</span><span class="s2">/Spec_Lock"</span><span class="p">,</span> <span class="no">File</span><span class="o">::</span><span class="no">CREAT</span><span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">f</span><span class="o">|</span>
    <span class="n">f</span><span class="p">.</span><span class="nf">flock</span><span class="p">(</span><span class="no">File</span><span class="o">::</span><span class="no">LOCK_EX</span><span class="p">)</span>
    <span class="n">sources</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">source</span><span class="o">|</span>
      <span class="no">UI</span><span class="p">.</span><span class="nf">section</span> <span class="s2">"Updating spec repo `</span><span class="si">#{</span><span class="n">source</span><span class="p">.</span><span class="nf">name</span><span class="si">}</span><span class="s2">`"</span> <span class="k">do</span>
        <span class="n">changed_source_paths</span> <span class="o">=</span> <span class="n">source</span><span class="p">.</span><span class="nf">update</span><span class="p">(</span><span class="n">show_output</span><span class="p">)</span>
        <span class="n">changed_spec_paths</span><span class="p">[</span><span class="n">source</span><span class="p">]</span> <span class="o">=</span> <span class="n">changed_source_paths</span> <span class="k">if</span> <span class="n">changed_source_paths</span><span class="p">.</span><span class="nf">count</span> <span class="o">&gt;</span> <span class="mi">0</span>
        <span class="n">source</span><span class="p">.</span><span class="nf">verify_compatibility!</span>
      <span class="k">end</span>
    <span class="k">end</span>
  <span class="k">end</span>
  <span class="n">update_search_index_if_needed_in_background</span><span class="p">(</span><span class="n">changed_spec_paths</span><span class="p">)</span>
<span class="k">end</span>
</code></pre></div></div>

<ol>
  <li>获取指定名称的 source，对 aggregate 返回的全部 sources 进行 filter，如未指定则 sources 全量。</li>
  <li>挨个调用 <code class="language-plaintext highlighter-rouge">source.update(show_output)</code>，注意 Git 和 CDN 仓库的更新方式的不同。</li>
</ol>

<h3 id="git-仓库更新">Git 仓库更新</h3>

<p>Git 仓库更新本质就是 Git 操作，即 <code class="language-plaintext highlighter-rouge">git pull</code>、<code class="language-plaintext highlighter-rouge">git checkout</code> 命令：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">update</span><span class="p">(</span><span class="n">show_output</span><span class="p">)</span>
  <span class="k">return</span> <span class="p">[]</span> <span class="k">if</span> <span class="n">unchanged_github_repo?</span>
  <span class="n">prev_commit_hash</span> <span class="o">=</span> <span class="n">git_commit_hash</span>
  <span class="n">update_git_repo</span><span class="p">(</span><span class="n">show_output</span><span class="p">)</span>
  <span class="vi">@versions_by_name</span><span class="p">.</span><span class="nf">clear</span>
  <span class="n">refresh_metadata</span>
  <span class="k">if</span> <span class="n">version</span> <span class="o">=</span> <span class="n">metadata</span><span class="p">.</span><span class="nf">last_compatible_version</span><span class="p">(</span><span class="no">Version</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="no">CORE_VERSION</span><span class="p">))</span>
    <span class="n">tag</span> <span class="o">=</span> <span class="s2">"v</span><span class="si">#{</span><span class="n">version</span><span class="si">}</span><span class="s2">"</span>
    <span class="no">CoreUI</span><span class="p">.</span><span class="nf">warn</span> <span class="s2">"Using the ..."</span>
    <span class="n">repo_git</span><span class="p">([</span><span class="s1">'checkout'</span><span class="p">,</span> <span class="n">tag</span><span class="p">])</span>
  <span class="k">end</span>
  <span class="n">diff_until_commit_hash</span><span class="p">(</span><span class="n">prev_commit_hash</span><span class="p">)</span>
<span class="k">end</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">#update_git_repo</code> 就是 <code class="language-plaintext highlighter-rouge">git fetch</code> + <code class="language-plaintext highlighter-rouge">git reset --hard [HEAD]</code> 的结合体，更新后会进行 cocoapods 版本兼容检查，最终输出 diff 信息。</p>

<h3 id="cdn-仓库更新">CDN 仓库更新</h3>

<p>Git 仓库是可以通过 Commit 信息来进行增量更新，那以静态资源方式缓存的 CDN 仓库是如何更新数据的呢 ？</p>

<p>像浏览器或本地缓存<strong>本质是利用 ETag 来进行 Cache-Control</strong>，关于 CDN 缓存可以看这篇：<a href="https://zhuanlan.zhihu.com/p/65722520" title="传送门">传送门</a>。</p>

<p>而 ETag 就是一串字符，内容通常是数据的哈希值，由服务器返回。首次请求后会在本地缓存起来，并在后续的请求中携带上 ETag 来确定缓存是否需要更新。如果 ETag 值相同，说明资源未更改，服务器会返回 304（Not Modified）响应码。</p>

<p>Core 的实现也是如此，它会将各请求所对应的 ETag 以文件形式存储：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440155-6a0b4fd1-944d-4462-b7ec-f0165a2ff986.jpeg#align=left&amp;display=inline&amp;height=477&amp;margin=%5Bobject%20Object%5D&amp;originHeight=477&amp;originWidth=1229&amp;size=0&amp;status=done&amp;style=none&amp;width=1229" alt="" /></p>

<p>⚠️ <strong>注意，在这个阶段 CDNSource 仅仅是更新当前目录下的索引文件</strong>，即 <code class="language-plaintext highlighter-rouge">all_pods_versions_x_x_x.txt</code>。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">update</span><span class="p">(</span><span class="n">_show_output</span><span class="p">)</span>
  <span class="vi">@check_existing_files_for_update</span> <span class="o">=</span> <span class="kp">true</span>
  <span class="k">begin</span>
    <span class="n">preheat_existing_files</span>
  <span class="k">ensure</span>
    <span class="vi">@check_existing_files_for_update</span> <span class="o">=</span> <span class="kp">false</span>
  <span class="k">end</span>
  <span class="p">[]</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">preheat_existing_files</span>
  <span class="n">files_to_update</span> <span class="o">=</span> <span class="n">files_definitely_to_update</span> <span class="o">+</span> <span class="n">deprecated_local_podspecs</span> <span class="o">-</span> <span class="p">[</span><span class="s1">'deprecated_podspecs.txt'</span><span class="p">]</span>

  <span class="n">concurrent_requests_catching_errors</span> <span class="k">do</span>
    <span class="n">loaders</span> <span class="o">=</span> <span class="n">files_to_update</span><span class="p">.</span><span class="nf">map</span> <span class="k">do</span> <span class="o">|</span><span class="n">file</span><span class="o">|</span>
      <span class="n">download_file_async</span><span class="p">(</span><span class="n">file</span><span class="p">)</span>
    <span class="k">end</span>
    <span class="no">Promises</span><span class="p">.</span><span class="nf">zip_futures_on</span><span class="p">(</span><span class="no">HYDRA_EXECUTOR</span><span class="p">,</span> <span class="o">*</span><span class="n">loaders</span><span class="p">).</span><span class="nf">wait!</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<h3 id="pod-repo-更新命令">Pod Repo 更新命令</h3>

<p>CocoaPods 对于 sources 仓库的更新也提供了命令行工具：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>pod repo update <span class="sb">`</span><span class="o">[</span>NAME]<span class="sb">`</span>
</code></pre></div></div>

<p>其实现如下：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods/command/repo/update.rb</span>

<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Command</span>
    <span class="k">class</span> <span class="nc">Repo</span> <span class="o">&lt;</span> <span class="no">Command</span>
      <span class="k">class</span> <span class="nc">Update</span> <span class="o">&lt;</span> <span class="no">Repo</span>
        <span class="k">def</span> <span class="nf">run</span>
          <span class="n">show_output</span> <span class="o">=</span> <span class="o">!</span><span class="n">config</span><span class="p">.</span><span class="nf">silent?</span>
          <span class="n">config</span><span class="p">.</span><span class="nf">sources_manager</span><span class="p">.</span><span class="nf">update</span><span class="p">(</span><span class="vi">@name</span><span class="p">,</span> <span class="n">show_output</span><span class="p">)</span>
          <span class="n">exclude_repos_dir_from_backup</span>
        <span class="k">end</span>
        <span class="c1"># ...</span>
      <span class="k">end</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>在命令初始化时会保存指定的 Source 仓库名称 <code class="language-plaintext highlighter-rouge">@name</code>，接着通过 Mixin 的 <code class="language-plaintext highlighter-rouge">config</code> 来获取 <code class="language-plaintext highlighter-rouge">sources_manager</code> 触发更新。</p>

<p>最后用一张图来收尾 CocoaPods Workflow：</p>

<p><img src="https://cdn.nlark.com/yuque/0/2020/jpeg/98641/1603554440228-d9d53de0-5268-413a-b71a-5acfa2bf145f.jpeg#align=left&amp;display=inline&amp;height=414&amp;margin=%5Bobject%20Object%5D&amp;originHeight=414&amp;originWidth=896&amp;size=0&amp;status=done&amp;style=none&amp;width=896" alt="" /></p>

<h1 id="总结">总结</h1>

<p>最后一篇 Core 的分析文章，重点介绍了它是如何管理 <code class="language-plaintext highlighter-rouge">PodSpec</code> 仓库以及 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件的更新和查找，总结如下：</p>

<ol>
  <li>了解 Source Manager 的各种数据结构以及它们之间的相互关系，各个类之间居然都做到了权责分明。</li>
  <li>通过对 Metadata 的分析了解了 Source 仓库的演变过程，并剖析了存在的问题。</li>
  <li>掌握了如何利用 CDN 来改造原有的 Git 仓库，优化 PodSpec 下载速度。</li>
  <li>发现原来 CLI 工具不仅仅可以提供给用户使用，内部调用也不是不可以。</li>
</ol>

<h1 id="知识点问题梳理">知识点问题梳理</h1>

<p>这里罗列了五个问题用来考察你是否已经掌握了这篇文章，如果没有建议你加入<strong>收藏</strong>再次阅读：</p>

<ol>
  <li><code class="language-plaintext highlighter-rouge">PodSpecs</code> 的聚合类有哪些，可以通过哪些手段来区分他们的类型 ？</li>
  <li>说说你对 <code class="language-plaintext highlighter-rouge">Aggregate</code> 类的理解，以及它的主要作用 ？</li>
  <li><code class="language-plaintext highlighter-rouge">Source</code> 类是如何更新 <code class="language-plaintext highlighter-rouge">PodSpec</code> ？</li>
  <li>Core 是如何对仓库进行分片的，它的分片方式是否支持配置 ？</li>
  <li>CDN 仓库是如何来更新 <code class="language-plaintext highlighter-rouge">PodSpec</code> 文件 ？</li>
</ol>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="CocoaPods 历险记" /><category term="Ruby" /><summary type="html"><![CDATA[引子 本文是 Core 的最后一篇，它与另外两篇文章「Podfile 解析逻辑」和「PodSpec 文件分析」共同支撑起 CocoaPods 世界的骨架。CocoaPods-Core 这个库之所以被命名为 Core 就是因为它包含了 Podfile -&gt; Spec Repo -&gt; PodSpec 这条完整的链路，将散落各地的依赖库连接起来并基于此骨架不断地完善功能。 从提供各种便利的命令行工具，到依赖库与主项目的自动集成，再到提供多样的 Xcode 编译配置、单元测试、资源管理等等，最终形成了我们所见的 CocoaPods。 今天我们就来聊聊 Spec Repo 这个 PodSpec 的聚合仓库以及它的演变与问题。 Source 作为 PodSpec 的聚合仓库，Spec Repo 记录着所有 pod 所发布的不同版本的 PodSpec 文件。该仓库对应到 Core 的数据结构为 Source，即为今天的主角。 整个 Source 的结构比较简单，它基本是围绕着 Git 来做文章，主要是对 PodSpec 文件进行各种查找更新操作。结构如下： # 用于检查 spec 是否符合当前 Source 要求 require 'cocoapods-core/source/acceptor' # 记录本地 source 的集合 require 'cocoapods-core/source/aggregate' # 用于校验 source 的错误和警告 require 'cocoapods-core/source/health_reporter' # source 管理器 require 'cocoapods-core/source/manager' # source 元数据 require 'cocoapods-core/source/metadata' module Pod class Source # 仓库默认的 Git 分支 DEFAULT_SPECS_BRANCH = 'master'.freeze # 记录仓库的元数据 attr_reader :metadata # 记录仓库的本地地址 attr_reader :repo # repo 仓库地址 ~/.cocoapods/repos/{repo_name} def initialize(repo) @repo = Pathname(repo).expand_path @versions_by_name = {} refresh_metadata end # 读取 Git 仓库中的 remote url 或 .git 目录 def url @url ||= begin remote = repo_git(%w(config --get remote.origin.url)) if !remote.empty? remote elsif (repo + '.git').exist? "file://#{repo}/.git" end end end def type git? ? 'git' : 'file system' end # ... end end Source 还有两个子类 CDNSource 和 TrunkSource，TrunkSouce 是 CocoaPods 的默认仓库。在版本 1.7.2 之前 Master Repo 的 URL 指向为 Github 的 Specs 仓库，这也是造成我们每次 pod install 或 pod update 慢的原因之一。它不仅保存了近 10 年来 PodSpec 文件同时还包括 Git 记录，再加上墙的原因，每次更新都非常痛苦。而在 1.7.2 之后 CocoaPods 的默认 Source 终于改为了 CDN 指向，同时支持按需下载，缓解了 pod 更新和磁盘占用过大问题。 Source 的依赖关系如下： 回到 Source 来看其如何初始化的，可以看到其构造函数 #initialize(repo) 将传入的 repo 地址保存后，直接调用了 #refresh_metadata 来完成元数据的加载： def refresh_metadata @metadata = Metadata.from_file(metadata_path) end def metadata_path repo + 'CocoaPods-version.yml' end Metadata Metadata 是保存在 repo 目录下，名为 CocoaPods-version.yml 的文件，用于记录该 Source 所支持的 CocoaPods 的版本以及仓库的分片规则。 autoload :Digest, 'digest/md5' require 'active_support/hash_with_indifferent_access' require 'active_support/core_ext/hash/indifferent_access' module Pod class Source class Metadata # 最低可支持的 CocoaPods 版本，对应字段 `min` attr_reader :minimum_cocoapods_version # 最高可支持的 CocoaPods 版本，对应字段 `max` attr_reader :maximum_cocoapods_version # 最新 CocoaPods 版本，对应字段 `last` attr_reader :latest_cocoapods_version # 规定截取的关键字段的前缀长度和数量 attr_reader :prefix_lengths # 可兼容的 CocoaPods 最新版本 attr_reader :last_compatible_versions # ... end end end 这里以笔者 💻 环境中 Master 仓库下的 CocoaPods-version.yml 文件内容为例： --- min: 1.0.0 last: 1.10.0.beta.1 prefix_lengths: - 1 - 1 - 1 最低支持版本为 1.0.0，最新可用版本为 1.10.0.beta.1，以及最后这个 prefix_lengths 为 [1, 1, 1] 的数组。那么这个 prefix_lengths 的作用是什么呢 ？ 要回答这个问题，我们先来看一张 Spec Repo 的目录结构图： 再 🤔 另外一个问题，为什么 CocoaPods 生成的目录结构是这样 ？ 其实在 2016 年 CocoaPods Spec 仓库下的所有文件都在同级目录，不像现在这样做了分片。这个是为了解决当时用户的吐槽：Github 下载慢，最终解决方案的结果就如你所见：将 Git 仓库进行了分片。 那么问题来了，为什么分片能够提升 Github 下载速度？ 很重要的一点是 CocoaPods 的 Spec Repo 本质上是 Git 仓库，而 Git 在做变更管理的时候，会记录目录的变更，每个子目录都会对应一个 Git model。而当目录中的文件数量过多的时候，Git 要找出对应的变更就变得十分困难。有兴趣的同学可以查看官方说明。 另外再补充一点，在 Linux 中最经典的一句话是：「一切皆文件」，不仅普通的文件和目录，就连块设备、管道、socket 等，也都是统一交给文件系统管理的。也就是说就算不用 Git 来管理 Specs 仓库，当目录下存在数以万计的文件时，如何高效查找目标文件也是需要考虑的问题。 Tips：关于文件系统层次结构有兴趣的同学可以查看FHS 标准，以及知乎这篇：传送门 回到 CocoaPods，如何对 Master 仓库目录进行分片就涉及到 metadata 类中的关键方法： def path_fragment(pod_name, version = nil) prefixes = if prefix_lengths.empty? [] else hashed = Digest::MD5.hexdigest(pod_name) prefix_lengths.map do |length| hashed.slice!(0, length) end end prefixes.concat([pod_name, version]).compact end #path_fragment 会依据 pod_name 和 version 来生成 pod 对应的索引目录： 首先对 pod_name 进行 MD5 计算获取摘要； 遍历 prefix_lengths 对生成的摘要不断截取指定的长度作为文件索引。 以 AFNetworking 为例： $ Digest::MD5.hexdigest('AFNetworking') "a75d452377f3996bdc4b623a5df25820" 由于我们的 prefix_lengths 为 [1, 1, 1] 数组，那么它将会从左到右依次截取出一个字母，即： a、7、5 ，这三个字母作为索引目录，它正好符合我们 👆 目录结构图中 AFNetworking 的所在位置。 Versions 要找到 Podfile 中限定版本号范围的 PodSpec 文件还需要需要最后一步，获取当前已发布的 Versions 列表，并通过比较 Version 得出最终所需的 PodSpec 文件。 在上一步已通过 metadata 和 pod_name 计算出 pod 所在目录，接着就是找到 pod 目录下的 Versions 列表： 获取 Versions： def versions(name) return nil unless specs_dir raise ArgumentError, 'No name' unless name pod_dir = pod_path(name) return unless pod_dir.exist? @versions_by_name[name] ||= pod_dir.children.map do |v| basename = v.basename.to_s begin Version.new(basename) if v.directory? &amp;&amp; basename[0, 1] != '.' rescue ArgumentError raise Informative, 'An unexpected version directory ...' end end.compact.sort.reverse end 该方法重点在于将 pod_dir 下的每个目录都转换成为了 Version 类型，并在最后进行了 sort 排序。 #versions 方法主要在 pod search 命令中被调用，后续会介绍。 来搂一眼 Version 类： class Version &lt; Pod::Vendor::Gem::Version METADATA_PATTERN = '(\+[0-9a-zA-Z\-\.]+)' VERSION_PATTERN = "[0-9]+(\\.[0-9a-zA-Z\\-]+)*#{METADATA_PATTERN}?" # ... end 该 Version 继承于 Gem::Version 并对其进行了扩展，实现了语义化版本号的标准，sort 排序也是基于语义化的版本来比较的，这里我们稍微展开一下。 Semantic Versioning 语义化版本号（Semantic Versioning 简称：SemVer）绝对是依赖管理工具绕不开的坎。语义化的版本就是让版本号更具语义化，可以传达出关于软件本身的一些重要信息而不只是简单的一串数字。 我们每次对 Pod 依赖进行更新，最后最重要的一步就是更新正确的版本号，一旦发布出去，再要更改就比较麻烦了。 SemVer 是由 Tom Preston-Werner 发起的一个关于软件版本号的命名规范，该作者为 Gravatars 创办者同时也是 GitHub 联合创始人。 那什么是语义化版本号有什么特别呢 ？我们以 AFNetworking 的 release tag 示例： 3.0.0 3.0.0-beta.1 3.0.0-beta.2 3.0.0-beta.3 3.0.1 这些 tags 并非随意递增的，它们背后正是遵循了语义化版本的标准。 基本规则 软件的版本通常由三位组成，如：X.Y.Z。 版本是严格递增的， 在发布重要版本时，可以发布 alpha, rc 等先行版本， alpha 和 rc 等修饰版本的关键字后面可以带上次数和 meta 信息， 版本格式： 主版本号.次版本号.修订号 版本号递增规则如下： Code status Stage Example version 新品首发 从 1.0.0 开始 1.0.0 向后兼容的 BugFix 增加补丁号 Z 1.0.1 向后兼容的 Feature 增加次版本号 Y 1.1.0 向后不兼容的改动 增加主版本号 X 2.0.0 重要版本的预览版 补丁号后添加 alpha, rc 2.1.0-rc.0 关于 CocoaPods 的 Version 使用描述，传送门。 CDNSource CocoaPods 在 1.7.2 版本正式将 Master 仓库托管到 Netlify 的 CDN 上，当时关于如何支持这一特性的文章和说明铺天盖地，这里还是推荐大家看官方说明。另外，当时感受是似乎国内的部分 iOS 同学都炸了，各种标题党：什么最完美的升级等等。 所以这里明确一下，对于 CocoaPods 的 Master 仓库支持了 CDN 的行为，仅解决了两个问题： 利用 CDN 节点的全球化部署解决内容分发慢，提高 Specs 资源的下载速度。 通过 Specs 按需下载摆脱了原有 Git Repo 模式下本地仓库的磁盘占用过大，操作卡的问题。 然而，仅仅对 PodSpec 增加了 CDN 根本没能解决 GFW 导致的 Github 源码校验、更新、下载慢的问题。 只能说路漫漫其修远兮。 PS：作为 iOS 工程师，就经常被前端同学 😒 。你看这 CocoaPods 也太垃圾了吧！！！一旦删掉 Pods 目录重新 install 就卡半天，缓存基本不生效，哪像 npm 多快 balabala … 先来看 CDNSource 结构： require 'cocoapods-core/source' # ... module Pod class CDNSource &lt; Source def initialize(repo) # 标记是否正在同步文件 @check_existing_files_for_update = false # 记录时间用于对比下载文件的新旧程度，以确认是否需要更新保存所下的资源 @startup_time = Time.new # 缓存查询过的 PodSpec 资源 @version_arrays_by_fragment_by_name = {} super(repo) end def url @url ||= File.read(repo.join('.url')).chomp.chomp('/') + '/' end def type 'CDN' end # ... end end Source 类是基于 Github Repo 来同步更新 PodSpec，而 CDNSource 则是基于 CDN 服务所返回的 Response，因此将 Source 类的大部分方法重写了一个遍，具体会在 SourceManager 一节来展开。 最后看一下 TrunkSource 类： module Pod class TrunkSource &lt; CDNSource # 新版落盘后仓库名称 TRUNK_REPO_NAME = 'trunk'.freeze TRUNK_REPO_URL = 'https://cdn.cocoapods.org/'.freeze def url @url ||= TRUNK_REPO_URL super end end end 核心就是重写了返回的 url，由于旧版 Spec 仓库名称为 master 为了加以区分，CDN 仓库则改名为 trunk。 Source Manager Manager 作为 source 的管理类，其主要任务为 source 的添加和获取，而对 PodSpec 文件的更新和查找行为则交由 source 各自实现。不过由于一个 pod 库可能对应多个不同的 source，这里又产生出 Aggregate 类来统一 PodSpec 的查询。 它们的关系如下： Manager 实现： module Pod class Source class Manager attr_reader :repos_dir def initialize(repos_dir) @repos_dir = Pathname(repos_dir).expand_path end def source_repos return [] unless repos_dir.exist? repos_dir.children.select(&amp;:directory?).sort_by { |d| d.basename.to_s.downcase } end def aggregate aggregate_with_repos(source_repos) end def aggregate_with_repos(repos) sources = repos.map { |path| source_from_path(path) } @aggregates_by_repos ||= {} @aggregates_by_repos[repos] ||= Source::Aggregate.new(sources) end def all aggregate.sources end # ... end end end Manager 类的初始化仅需要传入当前 repos 目录，即 ~/.cocoapods/repos，而 Aggregate 的生成则保存 repos_dir 了目录下的 Source，用于后续处理。 先看 Source 的生成，在 #source_from_path 中： def source_from_path(path) @sources_by_path ||= Hash.new do |hash, key| hash[key] = case when key.basename.to_s == Pod::TrunkSource::TRUNK_REPO_NAME TrunkSource.new(key) when (key + '.url').exist? CDNSource.new(key) else Source.new(key) end end @sources_by_path[path] end 以 repos_dir 下的目录名称来区分类型，而 CDNSource 则需要确保其目录下存在名为 .url 的文件。同时会对生成的 source 进行缓存。 最后看 Aggregate 结构，核心就两个 search 方法： module Pod class Source class Aggregate attr_reader :sources def initialize(sources) raise "Cannot initialize an aggregate with a nil source: (#{sources})" if sources.include?(nil) @sources = sources end # 查询依赖对应的 specs def search(dependency) ... end # 查询某个 pod 以发布的 specs def search_by_name(query, full_text_search = false) ... end # ... end end Source 源起 本节我们来谈谈 source 是如何添加到 repo_dir 目录下的。 由前面的介绍可知，每个 source 中自带 url，在 Source 类中 url 读取自 Git 仓库的 remote.origin.url 或本地 .git 目录，而在 CDNSource 中 url 则是读取自当前目录下的  .url 文件所保存的 URL 地址。 那 CDNSource 的  .url 文件是在什么时候被写入的呢 ？ 这需要从 Podfile 说起。很多老项目的 Podfile 开头部分大都会有一行或多行 source 命令： source 'https://github.com/CocoaPods/Specs.git' source 'https://github.com/artsy/Specs.git' 用于指定项目中 PodSpec 的查找源，这些指定源最终会保存在 ~/.cocoapods/repos 目录下的仓库。 当敲下 pod install 命令后，在 #resolve_dependencies 阶段的依赖分析中将同时完成 sources 的初始化。 # lib/cocoapods/installer/analyzer.rb def sources @sources ||= begin # 省略获取 podfile、plugins、dependencies 的 source url ... sources = ... result = sources.uniq.map do |source_url| sources_manager.find_or_create_source_with_url(source_url) end unless plugin_sources.empty? result.insert(0, *plugin_sources) plugin_sources.each do |source| sources_manager.add_source(source) end end result end end 获取 sources url 之后会通过 sources_manager 来完成 source 更新，逻辑在 CocoaPods 项目的 Manager 扩展中： # lib/cocoapods/sources_manager.rb module Pod class Source class Manager def find_or_create_source_with_url(url) source_with_url(url) || create_source_with_url(url) end def create_source_with_url(url) name = name_for_url(url) is_cdn = cdn_url?(url) # ... begin if is_cdn Command::Repo::AddCDN.parse([name, url]).run else Command::Repo::Add.parse([name, url]).run end rescue Informative =&gt; e raise Informative, # ... ensure UI.title_level = previous_title_level end source = source_with_url(url) raise "Unable to create a source with URL #{url}" unless source source end # ... end end end 查找会先调用 #source_with_url 进行缓存查询，如未命中则会先下载 Source 仓库，结束后重刷 aggreate 以更新 source。 # lib/cocoapods-core/source/manager.rb def source_with_url(url) url = canonic_url(url) url = 'https://github.com/cocoapods/specs' if url =~ %r{github.com[:/]+cocoapods/specs} all.find do |source| source.url &amp;&amp; canonic_url(source.url) == url end end def canonic_url(url) url.downcase.gsub(/\.git$/, '').gsub(%r{\/$}, '') end 另外，仓库的下载的则会通过 #cdn_url? 方法区分，最后的下载则 📦 在两个命令类中，概括如下： Repo::AddCDN：即  pod repo add-cdn 命令，仅有的操作是将 url 写入 .url 文件中。 Repo::Add：即 pod repo add 命令，对于普通类型的 Source 仓库下载本质就是 git clone 操作。 简化后源的添加流程如下： PodSpec 查询 同样在 #resolve_dependencies 的依赖仲裁阶段，当 Molinillo 依赖仲裁开始前，会触发缓存查询 #find_cached_set 并最终调用到 Aggregate 的 #search。完整调用栈放在 gist 上。 我们来看看 #search 入口： # lib/cocoapods-core/source/aggregate.rb def search(dependency) found_sources = sources.select { |s| s.search(dependency) } unless found_sources.empty? Specification::Set.new(dependency.root_name, found_sources) end end Aggregate 先遍历当前 sources 并进行 dependency 查找。由于 Git 仓库保存了完整的 PodSpecs，只要能在分片目录下查询到对应文件即可，最终结果会塞入 Specification::Set 返回。 Specification::Set 记录了当前 pod 关联的 Source，一个 pod 可能存在与多个不同的 Spec 仓库 中。 CDN 仓库查询 CDNSource 重写了 #search 实现： # lib/cocoapods-core/cdn_source.rb def search(query) unless specs_dir raise Informative, "Unable to find a source named: `#{name}`" end if query.is_a?(Dependency) query = query.root_name end fragment = pod_shard_fragment(query) ensure_versions_file_loaded(fragment) version_arrays_by_name = @version_arrays_by_fragment_by_name[fragment] || {} found = version_arrays_by_name[query].nil? ? nil : query if found set = set(query) set if set.specification_name == query end end 逻辑两步走： 通过 #ensure_versions_file_loaded 检查 all_pods_versions 文件，如果不存在会进行下载操作。 如果当前 source 包含查询的 pod，会创建 Specification::Set 作为查询结果，并在 #specification_name 方法内完成 PodSpec 的检查和下载。 1. all_pods_versions 文件下载 依据前面提到的分片规则会将 pod 名称 MD5 分割后拼成 URL。 以 AFNetworking 为例，经 #pod_shard_fragment 分割后获取的 fragment 为 [a, 7, 5]，则拼接后的 URL 为 https://cdn.cocoapods.org/all_pods_versions_a_7_5.txt，下载后的内容大致如下： AFNetworking/0.10.0/0.10.1/.../4.0.1 AppseeAnalytics/2.4.7/2.4.8/2.4.8.0/... DynamsoftBarcodeReader/7.1.0/... ... 所包含的这些 pod 都是分片后得到的相同的地址，因此会保存在同一份 all_pods_versions 中。 def ensure_versions_file_loaded(fragment) return if !@version_arrays_by_fragment_by_name[fragment].nil? &amp;&amp; !@check_existing_files_for_update index_file_name = index_file_name_for_fragment(fragment) download_file(index_file_name) versions_raw = local_file(index_file_name, &amp;:to_a).map(&amp;:chomp) @version_arrays_by_fragment_by_name[fragment] = versions_raw.reduce({}) do |hash, row| row = row.split('/') pod = row.shift versions = row hash[pod] = versions hash end end def index_file_name_for_fragment(fragment) fragment_joined = fragment.join('_') fragment_joined = '_' + fragment_joined unless fragment.empty? "all_pods_versions#{fragment_joined}.txt" end 另外每一份 pods_version 都会对应生成一个文件用于保存 ETag，具体会在下一节会介绍。 2. PodSpec 文件下载 #specification_name 将从 all_pods_versions 索引文件中找出该 pod 所发布的版本号，依次检查下载对应版本的 PodSpec.json 文件。 module Pod class Specification class Set attr_reader :name attr_reader :sources def specification_name versions_by_source.each do |source, versions| next unless version = versions.first return source.specification(name, version).name end nil end def versions_by_source @versions_by_source ||= sources.each_with_object({}) do |source, result| result[source] = source.versions(name) end end # ... end end end 绕了一圈后回到 Source 的 #versions 方法，由于 CDN Source 不会全量下载 pod 的 PodSpec 文件，在 #version 的检查过程会进行下载操作。 Pod Search 查询命令 CocoaPods 还提供了命令行工具 cocoapods-search 用于已发布的 PodSpec 查找： $ pod search `QUERY` 它提供了 Web 查询和本地查询。本地查询则不同于 #search，它需要调用 Aggregate 的 #search_by_name ，其实现同 #search 类似，最终也会走到 Source 的 #versions 方法。 注意，Gti 仓库的 #search_by_name 查询仍旧为文件查找，不会调用其 #versions 方法。 Repo 更新 pod install 执行过程如果带上了 --repo-update 命令则在 #resolve_dependencies 阶段会触发 #update_repositories 更新 Spec 仓库： # lib/cocoapods/installer/analyzer.rb def update_repositories sources.each do |source| if source.updateable? sources_manager.update(source.name, true) else UI.message "Skipping ..." end end @specs_updated = true end 不过 #update 的实现逻辑在 CocoaPods 项目的 Manager 扩展中： # lib/cocoapods/sources_managers.rb def update(source_name = nil, show_output = false) if source_name sources = [updateable_source_named(source_name)] else sources = updateable_sources end changed_spec_paths = {} # Do not perform an update if the repos dir has not been setup yet. return unless repos_dir.exist? File.open("#{repos_dir}/Spec_Lock", File::CREAT) do |f| f.flock(File::LOCK_EX) sources.each do |source| UI.section "Updating spec repo `#{source.name}`" do changed_source_paths = source.update(show_output) changed_spec_paths[source] = changed_source_paths if changed_source_paths.count &gt; 0 source.verify_compatibility! end end end update_search_index_if_needed_in_background(changed_spec_paths) end 获取指定名称的 source，对 aggregate 返回的全部 sources 进行 filter，如未指定则 sources 全量。 挨个调用 source.update(show_output)，注意 Git 和 CDN 仓库的更新方式的不同。 Git 仓库更新 Git 仓库更新本质就是 Git 操作，即 git pull、git checkout 命令： def update(show_output) return [] if unchanged_github_repo? prev_commit_hash = git_commit_hash update_git_repo(show_output) @versions_by_name.clear refresh_metadata if version = metadata.last_compatible_version(Version.new(CORE_VERSION)) tag = "v#{version}" CoreUI.warn "Using the ..." repo_git(['checkout', tag]) end diff_until_commit_hash(prev_commit_hash) end #update_git_repo 就是 git fetch + git reset --hard [HEAD] 的结合体，更新后会进行 cocoapods 版本兼容检查，最终输出 diff 信息。 CDN 仓库更新 Git 仓库是可以通过 Commit 信息来进行增量更新，那以静态资源方式缓存的 CDN 仓库是如何更新数据的呢 ？ 像浏览器或本地缓存本质是利用 ETag 来进行 Cache-Control，关于 CDN 缓存可以看这篇：传送门。 而 ETag 就是一串字符，内容通常是数据的哈希值，由服务器返回。首次请求后会在本地缓存起来，并在后续的请求中携带上 ETag 来确定缓存是否需要更新。如果 ETag 值相同，说明资源未更改，服务器会返回 304（Not Modified）响应码。 Core 的实现也是如此，它会将各请求所对应的 ETag 以文件形式存储： ⚠️ 注意，在这个阶段 CDNSource 仅仅是更新当前目录下的索引文件，即 all_pods_versions_x_x_x.txt。 def update(_show_output) @check_existing_files_for_update = true begin preheat_existing_files ensure @check_existing_files_for_update = false end [] end def preheat_existing_files files_to_update = files_definitely_to_update + deprecated_local_podspecs - ['deprecated_podspecs.txt'] concurrent_requests_catching_errors do loaders = files_to_update.map do |file| download_file_async(file) end Promises.zip_futures_on(HYDRA_EXECUTOR, *loaders).wait! end end Pod Repo 更新命令 CocoaPods 对于 sources 仓库的更新也提供了命令行工具： $ pod repo update `[NAME]` 其实现如下： # lib/cocoapods/command/repo/update.rb module Pod class Command class Repo &lt; Command class Update &lt; Repo def run show_output = !config.silent? config.sources_manager.update(@name, show_output) exclude_repos_dir_from_backup end # ... end end end end 在命令初始化时会保存指定的 Source 仓库名称 @name，接着通过 Mixin 的 config 来获取 sources_manager 触发更新。 最后用一张图来收尾 CocoaPods Workflow： 总结 最后一篇 Core 的分析文章，重点介绍了它是如何管理 PodSpec 仓库以及 PodSpec 文件的更新和查找，总结如下： 了解 Source Manager 的各种数据结构以及它们之间的相互关系，各个类之间居然都做到了权责分明。 通过对 Metadata 的分析了解了 Source 仓库的演变过程，并剖析了存在的问题。 掌握了如何利用 CDN 来改造原有的 Git 仓库，优化 PodSpec 下载速度。 发现原来 CLI 工具不仅仅可以提供给用户使用，内部调用也不是不可以。 知识点问题梳理 这里罗列了五个问题用来考察你是否已经掌握了这篇文章，如果没有建议你加入收藏再次阅读： PodSpecs 的聚合类有哪些，可以通过哪些手段来区分他们的类型 ？ 说说你对 Aggregate 类的理解，以及它的主要作用 ？ Source 类是如何更新 PodSpec ？ Core 是如何对仓库进行分片的，它的分片方式是否支持配置 ？ CDN 仓库是如何来更新 PodSpec 文件 ？]]></summary></entry><entry><title type="html">Podspec 文件分析</title><link href="https://www.desgard.com/2020/10/12/cocoapods-story-5.html" rel="alternate" type="text/html" title="Podspec 文件分析" /><published>2020-10-12T00:00:00-08:00</published><updated>2020-10-12T00:00:00-08:00</updated><id>https://www.desgard.com/2020/10/12/cocoapods-story-5</id><content type="html" xml:base="https://www.desgard.com/2020/10/12/cocoapods-story-5.html"><![CDATA[<h1 id="引子">引子</h1>

<p>在上文 <a href="/2020/09/16/cocoapods-story-4.html">Podfile 解析逻辑</a> 中（建议先阅读这篇文章），我们以 Xcode 工程结构作为切入点介绍了 Podfile 背后对应的数据结构，剖析了 <code class="language-plaintext highlighter-rouge">Podfile</code> 文件是如何解析与加载，并最终 <em>“入侵”</em> 项目影响其工程结构的。今天我们来聊一聊 <a href="https://link.zhihu.com/?target=https%3A//github.com/CocoaPods/Core">CocoaPods-Core</a> 中的另一个重要文件 — <code class="language-plaintext highlighter-rouge">Podspec</code> 以及它所撑起的 CocoaPods 世界。</p>

<p>一个 <code class="language-plaintext highlighter-rouge">Pod</code> 的创建和发布离不开 <code class="language-plaintext highlighter-rouge">.podspec</code> 文件，它可以很简单也能复杂，如 <a href="https://github.com/Tencent/QMUI_iOS/blob/master/QMUIKit.podspec">QMUIKit</a>（后续介绍)。</p>

<p>今天我们就直奔主题，来分析 <code class="language-plaintext highlighter-rouge">Podspec</code> 文件。</p>

<h1 id="podspec">Podspec</h1>

<p><code class="language-plaintext highlighter-rouge">Podspec</code> 是用于 <strong>描述一个 Pod 库的源代码和资源将如何被打包编译成链接库或 framework 的文件</strong> ，而 <code class="language-plaintext highlighter-rouge">Podspec</code> 中的这些描述内容最终将映会映射到 <code class="language-plaintext highlighter-rouge">Specification</code> 类中（以下简称 <strong>Spec</strong>）。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123337307-c263f917-e45d-46c7-be0c-74fa1bc663e0.png" alt="" /></p>

<p>现在让我们来重新认识 <code class="language-plaintext highlighter-rouge">Podspec</code>。</p>

<h2 id="podspec-初探">Podspec 初探</h2>

<p><code class="language-plaintext highlighter-rouge">Podspec</code> 支持的文件格式为 <code class="language-plaintext highlighter-rouge">.podspec</code> 和 <code class="language-plaintext highlighter-rouge">.json</code> 两种，而 <code class="language-plaintext highlighter-rouge">.podspec</code> 本质是 Ruby 文件。</p>

<p>问题来了，为什么是 JSON 格式而不像 <code class="language-plaintext highlighter-rouge">Podfile</code> 一样支持 YAML 呢？</p>

<p>笔者的理解：由于 <code class="language-plaintext highlighter-rouge">Podspec</code> 文件会满世界跑，它可能存在于 CocoaPods 的 <a href="https://cdn.cocoapods.org/">CDN Service</a>、<a href="https://github.com/CocoaPods/Specs">Speces Repo</a> 或者你们的私有 Specs Repo 上，因此采用  JSON 的文件在网络传输中会更友好。而 <code class="language-plaintext highlighter-rouge">Podfile</code> 更多的场景是用于序列化，它需要在项目中生成一份经依赖仲裁后的 <code class="language-plaintext highlighter-rouge">Podfile</code> 快照，用于后续的对比。</p>

<h3 id="podspec-1">Podspec</h3>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">Pod</span><span class="o">::</span><span class="no">Spec</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="n">spec</span><span class="o">|</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">name</span>         <span class="o">=</span> <span class="s1">'Reachability'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">version</span>      <span class="o">=</span> <span class="s1">'3.1.0'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">license</span>      <span class="o">=</span> <span class="p">{</span> <span class="ss">:type</span> <span class="o">=&gt;</span> <span class="s1">'BSD'</span> <span class="p">}</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">homepage</span>     <span class="o">=</span> <span class="s1">'https://github.com/tonymillion/Reachability'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">authors</span>      <span class="o">=</span> <span class="p">{</span> <span class="s1">'Tony Million'</span> <span class="o">=&gt;</span> <span class="s1">'tonymillion@gmail.com'</span> <span class="p">}</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">summary</span>      <span class="o">=</span> <span class="s1">'ARC and GCD Compatible Reachability Class for iOS and OS X.'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">source</span>       <span class="o">=</span> <span class="p">{</span> <span class="ss">:git</span> <span class="o">=&gt;</span> <span class="s1">'https://github.com/tonymillion/Reachability.git'</span><span class="p">,</span> <span class="ss">:tag</span> <span class="o">=&gt;</span> <span class="s2">"v</span><span class="si">#{</span><span class="n">spec</span><span class="p">.</span><span class="nf">version</span><span class="si">}</span><span class="s2">"</span> <span class="p">}</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">source_files</span> <span class="o">=</span> <span class="s1">'Reachability.{h,m}'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">framework</span>    <span class="o">=</span> <span class="s1">'SystemConfiguration'</span>
<span class="k">end</span>
</code></pre></div></div>

<p>上面这份 <code class="language-plaintext highlighter-rouge">Reachability.podspec</code> 配置，基本通过命令行 <code class="language-plaintext highlighter-rouge">pod lib create NAME</code> 就能帮我们完成。除此之外我们能做的更多，比如，默认情况下 CococaPods 会为每个 <code class="language-plaintext highlighter-rouge">Pod</code> framework 生成一个对应的 <code class="language-plaintext highlighter-rouge">modulemap</code> 文件，它将包含 <code class="language-plaintext highlighter-rouge">Podspec</code> 中指定的公共 headers。如果需要自定义引入的 header 文件，仅需配置 <code class="language-plaintext highlighter-rouge">moduel_map</code> 即可完成。</p>

<p>下面是进阶版配置：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">Pod</span><span class="o">::</span><span class="no">Spec</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="n">spec</span><span class="o">|</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">name</span>         <span class="o">=</span> <span class="s1">'Reachability'</span>
  <span class="c1"># 省略与前面相同部分的配置 ...</span>
  
  <span class="n">spec</span><span class="p">.</span><span class="nf">module_name</span>   <span class="o">=</span> <span class="s1">'Rich'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">swift_version</span> <span class="o">=</span> <span class="s1">'4.0'</span>

  <span class="n">spec</span><span class="p">.</span><span class="nf">ios</span><span class="p">.</span><span class="nf">deployment_target</span>  <span class="o">=</span> <span class="s1">'9.0'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">osx</span><span class="p">.</span><span class="nf">deployment_target</span>  <span class="o">=</span> <span class="s1">'10.10'</span>

  <span class="n">spec</span><span class="p">.</span><span class="nf">source_files</span>       <span class="o">=</span> <span class="s1">'Reachability/common/*.swift'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">ios</span><span class="p">.</span><span class="nf">source_files</span>   <span class="o">=</span> <span class="s1">'Reachability/ios/*.swift'</span><span class="p">,</span> <span class="s1">'Reachability/extensions/*.swift'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">osx</span><span class="p">.</span><span class="nf">source_files</span>   <span class="o">=</span> <span class="s1">'Reachability/osx/*.swift'</span>

  <span class="n">spec</span><span class="p">.</span><span class="nf">framework</span>      <span class="o">=</span> <span class="s1">'SystemConfiguration'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">ios</span><span class="p">.</span><span class="nf">framework</span>  <span class="o">=</span> <span class="s1">'UIKit'</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">osx</span><span class="p">.</span><span class="nf">framework</span>  <span class="o">=</span> <span class="s1">'AppKit'</span>

  <span class="n">spec</span><span class="p">.</span><span class="nf">dependency</span> <span class="s1">'SomeOtherPod'</span>
<span class="k">end</span>
</code></pre></div></div>

<p>像 👆 我们为不同的系统指定了不同的源码和依赖等，当然可配置的不只这些。</p>

<p><code class="language-plaintext highlighter-rouge">Podspec</code> 支持的完整配置分类如下：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123356225-0e9d5db0-e68e-4808-b198-735931d3a780.png" alt="" /></p>

<p>想了解更多的配置选项：<a href="https://guides.cocoapods.org/syntax/Podspec.html">传送门</a>。</p>

<h3 id="convention-over-configuration">Convention Over Configuration</h3>

<p>说到配置，不得不提一下 <code class="language-plaintext highlighter-rouge">CoC</code> 约定大于配置。约定大于配置算是在软件工程较早出现的概念的了，大意是：<strong>为了简单起见，我们的代码需要按照一定的约定来编写</strong>（如代码放在什么目录，用什么文件名，用什么类名等)。 这样既简化了配置文件，同时也降低了学习成本。</p>

<p>约定大于配置可以说是通过 <a href="https://www.wikiwand.com/en/Ruby_on_Rails">Ruby on Rails</a> 发扬光大的。尽管它一直饱受争议，但是主流语言的依赖管理工具，如 <code class="language-plaintext highlighter-rouge">Maven</code>、<code class="language-plaintext highlighter-rouge">npm</code> 等都遵循 <code class="language-plaintext highlighter-rouge">CoC</code> 进行不断演进的，因为 <code class="language-plaintext highlighter-rouge">CoC</code> 能够有效帮助开发者减轻选择的痛感，减少无意义的选择。一些新的语言也吸收了这个思想，比如 Go 语言。如果用 C/C++ 可能需要定义复杂的 Makefile 来定义编译的规则，以及如何运行测试用例，而在 Go 中这些都是约定好的。</p>

<p>举个 🌰 ：<code class="language-plaintext highlighter-rouge">Podfile</code> 中是可以指定 pod library 所链接的 Xcode project，不过大多情况下无需配置，CocoaPods 会自动查找 <code class="language-plaintext highlighter-rouge">Podfile</code> 所在的同级目录下所对应的工程文件 <code class="language-plaintext highlighter-rouge">.project</code> 。</p>

<h2 id="spec-的核心数据结构">Spec 的核心数据结构</h2>

<h3 id="specification">Specification</h3>

<p>在数据结构上 <code class="language-plaintext highlighter-rouge">Specification</code> 与 <a href="https://looseyi.github.io/post/sourcecode-cocoapods/04-cocoapods-podfile/#targetdefinition">TargetDefinition</a> 是类似的，<strong>同为多叉树结构</strong>。简化后的 <code class="language-plaintext highlighter-rouge">Spec</code> 的类如下：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">require</span> <span class="s1">'active_support/core_ext/string/strip.rb'</span>
<span class="c1"># 记录对应 platform 上 Spec 的其他 pod 依赖</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/specification/consumer'</span>
<span class="c1"># 解析 DSL</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/specification/dsl'</span>
<span class="c1"># 校验 Spec 的正确性，并抛出对应的错误和警告</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/specification/linter'</span>
<span class="c1"># 用于解析 DSL 内容包含的配置信息</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/specification/root_attribute_accessors'</span>
<span class="c1"># 记录一个 Pod 所有依赖的 Spec 来源信息</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/specification/set'</span>
<span class="c1"># json 格式数据解析</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/specification/json'</span>

<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Specification</span>
    <span class="kp">include</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Specification</span><span class="o">::</span><span class="no">DSL</span>
    <span class="kp">include</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Specification</span><span class="o">::</span><span class="no">DSL</span><span class="o">::</span><span class="no">Deprecations</span>
    <span class="kp">include</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Specification</span><span class="o">::</span><span class="no">RootAttributesAccessors</span>
    <span class="kp">include</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Specification</span><span class="o">::</span><span class="no">JSONSupport</span>
 
    <span class="c1"># `subspec` 的父节点</span>
    <span class="nb">attr_reader</span> <span class="ss">:parent</span>
    <span class="c1"># `Spec` 的唯一 id，由 name + version 的 hash 构成</span>
    <span class="nb">attr_reader</span> <span class="ss">:hash_value</span>
    <span class="c1"># 记录 `Spec` 的配置信息 </span>
    <span class="nb">attr_accessor</span> <span class="ss">:attributes_hash</span>
    <span class="c1"># `Spec` 包含的 `subspec`</span>
    <span class="nb">attr_accessor</span> <span class="ss">:subspecs</span>
     
    <span class="c1"># 递归调用获取 Specification 的根节点</span>
    <span class="k">def</span> <span class="nf">root</span>
      <span class="n">parent</span> <span class="p">?</span> <span class="n">parent</span><span class="p">.</span><span class="nf">root</span> <span class="p">:</span> <span class="nb">self</span>
    <span class="k">end</span>
     
	 <span class="k">def</span> <span class="nf">hash</span>
   	<span class="k">if</span> <span class="vi">@hash_value</span><span class="p">.</span><span class="nf">nil?</span>
      	<span class="vi">@hash_value</span> <span class="o">=</span> <span class="p">(</span><span class="nb">name</span><span class="p">.</span><span class="nf">hash</span> <span class="o">*</span> <span class="mi">53</span><span class="p">)</span> <span class="o">^</span> <span class="n">version</span><span class="p">.</span><span class="nf">hash</span>
		<span class="k">end</span>
      <span class="vi">@hash_value</span>
    <span class="k">end</span>
     
    <span class="c1"># ...</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">Specification</code> 同样用 map <code class="language-plaintext highlighter-rouge">attributes_hash</code> 来记录配置信息。</p>

<p>注意，这里的 parent 是为 <code class="language-plaintext highlighter-rouge">subspec</code> 保留的，用于指向其父节点的 <code class="language-plaintext highlighter-rouge">Spec</code>。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123372255-dae8539b-97d6-4219-8c0a-875c57bc53cd.png" alt="" /></p>

<h3 id="subspecs">Subspecs</h3>

<p>乍一听 <code class="language-plaintext highlighter-rouge">Subspec</code> 这个概念似乎有一些抽象，不过当你理解了上面的描述，就能明白什么是 <code class="language-plaintext highlighter-rouge">Subspec</code> 了。我们知道在 Xcode 项目中，target 作为最小的可编译单元，它编译后的产物为链接库或 framework。而在 CocoaPods 的世界里这些 targets 则是由 <code class="language-plaintext highlighter-rouge">Spec</code> 文件来描述的，它还能拆分成一个或者多个 <code class="language-plaintext highlighter-rouge">Subspec</code>，我们暂且把它称为 <code class="language-plaintext highlighter-rouge">Spec</code> 的 <strong>子模块</strong>，子模块也是用 <strong>Specification</strong> 类来描述的。</p>

<p><strong>子模块可以单独作为依赖被引入到项目中。</strong>它有几个特点：</p>

<ul>
  <li>未指定 <code class="language-plaintext highlighter-rouge">default_subspec</code> 的情况下，<code class="language-plaintext highlighter-rouge">Spec</code> 的全部子模块都将作为依赖被引入；</li>
  <li>子模块会主动继承其父节点 <code class="language-plaintext highlighter-rouge">Spec</code> 中定义的 <code class="language-plaintext highlighter-rouge">attributes_hash</code>；</li>
  <li>子模块可以指定自己的源代码、资源文件、编译配置、依赖等；</li>
  <li>同一 <code class="language-plaintext highlighter-rouge">Spec</code> 内部的子模块是可以有依赖关系的；</li>
  <li>每个子模块在 <code class="language-plaintext highlighter-rouge">pod push</code> 的时候是需要被 lint 通过的；</li>
</ul>

<p>光听总结似乎还是云里雾里，祭出 QMUI 让大家感受一下：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">Pod</span><span class="o">::</span><span class="no">Spec</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="n">s</span><span class="o">|</span>
  <span class="n">s</span><span class="p">.</span><span class="nf">name</span>             <span class="o">=</span> <span class="s2">"QMUIKit"</span>
  <span class="n">s</span><span class="p">.</span><span class="nf">version</span>          <span class="o">=</span> <span class="s2">"4.2.1"</span>
  <span class="c1"># ...</span>
  <span class="n">s</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'QMUICore'</span> <span class="k">do</span> <span class="o">|</span><span class="n">ss</span><span class="o">|</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">source_files</span> <span class="o">=</span> <span class="s1">'QMUIKit/QMUIKit.h'</span><span class="p">,</span> <span class="s1">'QMUIKit/QMUICore'</span><span class="p">,</span> <span class="s1">'QMUIKit/UIKitExtensions'</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">dependency</span> <span class="s1">'QMUIKit/QMUIWeakObjectContainer'</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">dependency</span> <span class="s1">'QMUIKit/QMUILog'</span>
  <span class="k">end</span>

  <span class="n">s</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'QMUIWeakObjectContainer'</span> <span class="k">do</span> <span class="o">|</span><span class="n">ss</span><span class="o">|</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">source_files</span> <span class="o">=</span> <span class="s1">'QMUIKit/QMUIComponents/QMUIWeakObjectContainer.{h,m}'</span>
  <span class="k">end</span>

  <span class="n">s</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'QMUILog'</span> <span class="k">do</span> <span class="o">|</span><span class="n">ss</span><span class="o">|</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">source_files</span> <span class="o">=</span> <span class="s1">'QMUIKit/QMUIComponents/QMUILog/*.{h,m}'</span>
  <span class="k">end</span>

  <span class="n">s</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'QMUIComponents'</span> <span class="k">do</span> <span class="o">|</span><span class="n">ss</span><span class="o">|</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">dependency</span> <span class="s1">'QMUIKit/QMUICore'</span>
     
    <span class="n">ss</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'QMUIButton'</span> <span class="k">do</span> <span class="o">|</span><span class="n">sss</span><span class="o">|</span>
      <span class="n">sss</span><span class="p">.</span><span class="nf">source_files</span> <span class="o">=</span> <span class="s1">'QMUIKit/QMUIComponents/QMUIButton/QMUIButton.{h,m}'</span>
    <span class="k">end</span>
    <span class="c1"># 此处省略 59 个 Components</span>
  <span class="k">end</span>
  <span class="c1"># ...</span>
<span class="k">end</span>
</code></pre></div></div>

<blockquote>
  <p>不吹不黑，QMUI 是笔者见过国内开源作品中代码注释非常详尽且提供完整 Demo 的项目之一。</p>
</blockquote>

<p>整个 QMUIKit 的 <code class="language-plaintext highlighter-rouge">Spec</code> 文件中，总共定义了 <strong>64</strong> 个 <code class="language-plaintext highlighter-rouge">subspec</code> 子模块，同时这些子模块之间还做了分层。比如 QMUICore：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123383555-32462e33-aaf5-4004-899f-cfd384e1e04e.png" alt="" /></p>

<p>另外补充一点，CocoaPods 支持了不同类型的 <code class="language-plaintext highlighter-rouge">SubSpec</code>：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># lib/cocoapods-core/specification/dsl/attribute_support.rb</span>

<span class="no">SUPPORTED_SPEC_TYPES</span> <span class="o">=</span> <span class="p">[</span><span class="ss">:library</span><span class="p">,</span> <span class="ss">:app</span><span class="p">,</span> <span class="ss">:test</span><span class="p">].</span><span class="nf">freeze</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">:app</code> 和 <code class="language-plaintext highlighter-rouge">:test</code> 用于在项目中集成单元测试代码的 <code class="language-plaintext highlighter-rouge">Subspec</code>。</p>

<h2 id="podspec-from-json">Podspec From JSON</h2>

<p>有了上文 <code class="language-plaintext highlighter-rouge">Podfile</code> 的了解，这次我们对 <code class="language-plaintext highlighter-rouge">Podspec</code> 的文件加载会更加轻车熟路。首先是由 <code class="language-plaintext highlighter-rouge">#from_file</code> 方法进行文件路径和内容编码格式的检查，将加载的内容转入 <code class="language-plaintext highlighter-rouge">#from_string</code>：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_file</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">subspec_name</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
  <span class="n">path</span> <span class="o">=</span> <span class="no">Pathname</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
  <span class="k">unless</span> <span class="n">path</span><span class="p">.</span><span class="nf">exist?</span>
    <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"No Podspec exists at path `</span><span class="si">#{</span><span class="n">path</span><span class="si">}</span><span class="s2">`."</span>
  <span class="k">end</span>

  <span class="n">string</span> <span class="o">=</span> <span class="no">File</span><span class="p">.</span><span class="nf">open</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s1">'r:utf-8'</span><span class="p">,</span> <span class="o">&amp;</span><span class="ss">:read</span><span class="p">)</span>
  <span class="c1"># Work around for Rubinius incomplete encoding in 1.9 mode</span>
  <span class="k">if</span> <span class="n">string</span><span class="p">.</span><span class="nf">respond_to?</span><span class="p">(</span><span class="ss">:encoding</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="n">string</span><span class="p">.</span><span class="nf">encoding</span><span class="p">.</span><span class="nf">name</span> <span class="o">!=</span> <span class="s1">'UTF-8'</span>
    <span class="n">string</span><span class="p">.</span><span class="nf">encode!</span><span class="p">(</span><span class="s1">'UTF-8'</span><span class="p">)</span>
  <span class="k">end</span>

  <span class="n">from_string</span><span class="p">(</span><span class="n">string</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">subspec_name</span><span class="p">)</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_string</span><span class="p">(</span><span class="n">spec_contents</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">subspec_name</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
  <span class="n">path</span> <span class="o">=</span> <span class="no">Pathname</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">path</span><span class="p">).</span><span class="nf">expand_path</span>
  <span class="n">spec</span> <span class="o">=</span> <span class="kp">nil</span>
  <span class="k">case</span> <span class="n">path</span><span class="p">.</span><span class="nf">extname</span>
  <span class="k">when</span> <span class="s1">'.podspec'</span>
    <span class="no">Dir</span><span class="p">.</span><span class="nf">chdir</span><span class="p">(</span><span class="n">path</span><span class="p">.</span><span class="nf">parent</span><span class="p">.</span><span class="nf">directory?</span> <span class="p">?</span> <span class="n">path</span><span class="p">.</span><span class="nf">parent</span> <span class="p">:</span> <span class="no">Dir</span><span class="p">.</span><span class="nf">pwd</span><span class="p">)</span> <span class="k">do</span>
      <span class="n">spec</span> <span class="o">=</span> <span class="o">::</span><span class="no">Pod</span><span class="p">.</span><span class="nf">_eval_Podspec</span><span class="p">(</span><span class="n">spec_contents</span><span class="p">,</span> <span class="n">path</span><span class="p">)</span>
      <span class="k">unless</span> <span class="n">spec</span><span class="p">.</span><span class="nf">is_a?</span><span class="p">(</span><span class="no">Specification</span><span class="p">)</span>
        <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"Invalid Podspec file at path `</span><span class="si">#{</span><span class="n">path</span><span class="si">}</span><span class="s2">`."</span>
      <span class="k">end</span>
    <span class="k">end</span>
  <span class="k">when</span> <span class="s1">'.json'</span>
    <span class="n">spec</span> <span class="o">=</span> <span class="no">Specification</span><span class="p">.</span><span class="nf">from_json</span><span class="p">(</span><span class="n">spec_contents</span><span class="p">)</span>
  <span class="k">else</span>
    <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"Unsupported specification format `</span><span class="si">#{</span><span class="n">path</span><span class="p">.</span><span class="nf">extname</span><span class="si">}</span><span class="s2">` for spec at `</span><span class="si">#{</span><span class="n">path</span><span class="si">}</span><span class="s2">`."</span>
  <span class="k">end</span>

  <span class="n">spec</span><span class="p">.</span><span class="nf">defined_in_file</span> <span class="o">=</span> <span class="n">path</span>
  <span class="n">spec</span><span class="p">.</span><span class="nf">subspec_by_name</span><span class="p">(</span><span class="n">subspec_name</span><span class="p">,</span> <span class="kp">true</span><span class="p">)</span>
<span class="k">end</span>
</code></pre></div></div>

<p>接着根据文件类型为 <code class="language-plaintext highlighter-rouge">.podspec</code> 和 <code class="language-plaintext highlighter-rouge">.json</code> 分别采用不同的解析方式。在  <strong>JSONSupport</strong> 模块内将 <code class="language-plaintext highlighter-rouge">#from_json</code> 的逻辑拆成了两部分：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># `lib/cocoapods-core/specification/json.rb`</span>
<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Specification</span>
    <span class="k">module</span> <span class="nn">JSONSupport</span>
    <span class="c1"># ①</span>
    <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_json</span><span class="p">(</span><span class="n">json</span><span class="p">)</span>
      <span class="nb">require</span> <span class="s1">'json'</span>
      <span class="nb">hash</span> <span class="o">=</span> <span class="no">JSON</span><span class="p">.</span><span class="nf">parse</span><span class="p">(</span><span class="n">json</span><span class="p">)</span>
      <span class="n">from_hash</span><span class="p">(</span><span class="nb">hash</span><span class="p">)</span>
    <span class="k">end</span>
    <span class="c1"># ②</span>
    <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_hash</span><span class="p">(</span><span class="nb">hash</span><span class="p">,</span> <span class="n">parent</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">,</span> <span class="ss">test_specification: </span><span class="kp">false</span><span class="p">,</span> <span class="ss">app_specification: </span><span class="kp">false</span><span class="p">)</span>
      <span class="n">attributes_hash</span> <span class="o">=</span> <span class="nb">hash</span><span class="p">.</span><span class="nf">dup</span>
      <span class="n">spec</span> <span class="o">=</span> <span class="no">Spec</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">parent</span><span class="p">,</span> <span class="kp">nil</span><span class="p">,</span> <span class="n">test_specification</span><span class="p">,</span> <span class="ss">:app_specification</span> <span class="o">=&gt;</span> <span class="n">app_specification</span><span class="p">)</span>
      <span class="n">subspecs</span> <span class="o">=</span> <span class="n">attributes_hash</span><span class="p">.</span><span class="nf">delete</span><span class="p">(</span><span class="s1">'subspecs'</span><span class="p">)</span>
      <span class="n">testspecs</span> <span class="o">=</span> <span class="n">attributes_hash</span><span class="p">.</span><span class="nf">delete</span><span class="p">(</span><span class="s1">'testspecs'</span><span class="p">)</span>
      <span class="n">appspecs</span> <span class="o">=</span> <span class="n">attributes_hash</span><span class="p">.</span><span class="nf">delete</span><span class="p">(</span><span class="s1">'appspecs'</span><span class="p">)</span>
  
      <span class="c1">## backwards compatibility with 1.3.0</span>
      <span class="n">spec</span><span class="p">.</span><span class="nf">test_specification</span> <span class="o">=</span> <span class="o">!</span><span class="n">attributes_hash</span><span class="p">[</span><span class="s1">'test_type'</span><span class="p">].</span><span class="nf">nil?</span>
  
      <span class="n">spec</span><span class="p">.</span><span class="nf">attributes_hash</span> <span class="o">=</span> <span class="n">attributes_hash</span>
      <span class="n">spec</span><span class="p">.</span><span class="nf">subspecs</span><span class="p">.</span><span class="nf">concat</span><span class="p">(</span><span class="n">subspecs_from_hash</span><span class="p">(</span><span class="n">spec</span><span class="p">,</span> <span class="n">subspecs</span><span class="p">,</span> <span class="kp">false</span><span class="p">,</span> <span class="kp">false</span><span class="p">))</span>
      <span class="n">spec</span><span class="p">.</span><span class="nf">subspecs</span><span class="p">.</span><span class="nf">concat</span><span class="p">(</span><span class="n">subspecs_from_hash</span><span class="p">(</span><span class="n">spec</span><span class="p">,</span> <span class="n">testspecs</span><span class="p">,</span> <span class="kp">true</span><span class="p">,</span> <span class="kp">false</span><span class="p">))</span>
      <span class="n">spec</span><span class="p">.</span><span class="nf">subspecs</span><span class="p">.</span><span class="nf">concat</span><span class="p">(</span><span class="n">subspecs_from_hash</span><span class="p">(</span><span class="n">spec</span><span class="p">,</span> <span class="n">appspecs</span><span class="p">,</span> <span class="kp">false</span><span class="p">,</span> <span class="kp">true</span><span class="p">))</span>
  
      <span class="n">spec</span>
    <span class="k">end</span>
    <span class="c1"># ③</span>
    <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">subspecs_from_hash</span><span class="p">(</span><span class="n">spec</span><span class="p">,</span> <span class="n">subspecs</span><span class="p">,</span> <span class="n">test_specification</span><span class="p">,</span> <span class="n">app_specification</span><span class="p">)</span>
      <span class="k">return</span> <span class="p">[]</span> <span class="k">if</span> <span class="n">subspecs</span><span class="p">.</span><span class="nf">nil?</span>
      <span class="n">subspecs</span><span class="p">.</span><span class="nf">map</span> <span class="k">do</span> <span class="o">|</span><span class="n">s_hash</span><span class="o">|</span>
        <span class="no">Specification</span><span class="p">.</span><span class="nf">from_hash</span><span class="p">(</span><span class="n">s_hash</span><span class="p">,</span> <span class="n">spec</span><span class="p">,</span>
                                <span class="ss">:test_specification</span> <span class="o">=&gt;</span> <span class="n">test_specification</span><span class="p">,</span>
                                <span class="ss">:app_specification</span> <span class="o">=&gt;</span> <span class="n">app_specification</span><span class="p">)</span>
      <span class="k">end</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>这里的逻辑也是比较简单：</p>

<ul>
  <li>① 将传入的字符串转换为 json；</li>
  <li>② 将转换后的 json 转换为 <code class="language-plaintext highlighter-rouge">Spec</code> 对象并将 json 转换为 <code class="language-plaintext highlighter-rouge">attributes_hash</code>，同时触发 ③；</li>
  <li>③ 通过 <code class="language-plaintext highlighter-rouge">self.subspecs_from_hash</code> 实现递归调用完成 <code class="language-plaintext highlighter-rouge">subspecs</code> 解析；</li>
</ul>

<blockquote>
  <p>Tips: 方法 ② 里的 <strong>Spec</strong> 是对 <code class="language-plaintext highlighter-rouge">Specification</code> 的别名。</p>
</blockquote>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123399989-8bef8979-4f1d-4ab5-984a-95f57e384a91.png" alt="" /></p>

<h2 id="podspec-from-ruby">Podspec From Ruby</h2>

<p><code class="language-plaintext highlighter-rouge">QMUIKit.podspec</code> 的文件内容，大家是否注意到其开头的声明：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">Pod</span><span class="o">::</span><span class="no">Spec</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="n">s</span><span class="o">|</span>
  <span class="n">s</span><span class="p">.</span><span class="nf">name</span>             <span class="o">=</span> <span class="s2">"QMUIKit"</span>
  <span class="n">s</span><span class="p">.</span><span class="nf">source_files</span>     <span class="o">=</span> <span class="s1">'QMUIKit/QMUIKit.h'</span>
  <span class="c1"># ...</span>
<span class="k">end</span>
</code></pre></div></div>

<p>发现没 <code class="language-plaintext highlighter-rouge">.podspec</code> 文件就是<strong>简单直接地声明了一个 <code class="language-plaintext highlighter-rouge">Specifiction</code> 对象</strong>，然后通过 block 块定制来完成配置。像 <code class="language-plaintext highlighter-rouge">name</code>、<code class="language-plaintext highlighter-rouge">source_files</code> 这些配置参数最终都会转换为方法调用并将值存入 <code class="language-plaintext highlighter-rouge">attributes_hash</code> 中。这些方法调用的实现方式分两种：</p>

<ol>
  <li>大部分配置是通过方法包装器 <code class="language-plaintext highlighter-rouge">attribute</code> 和 <code class="language-plaintext highlighter-rouge">root_attribute</code> 来动态添加的 setter 方法；</li>
  <li>对于复杂逻辑的配置则直接方法声明，如 <code class="language-plaintext highlighter-rouge">subspec</code> 、<code class="language-plaintext highlighter-rouge">dependency</code> 方法等（后续介绍)。</li>
</ol>

<h3 id="attribute-wrappter">attribute wrappter</h3>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># `lib/cocoapods-core/specification/dsl.rb`</span>
<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Specification</span>
    <span class="k">module</span> <span class="nn">DSL</span>
      <span class="kp">extend</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Specification</span><span class="o">::</span><span class="no">DSL</span><span class="o">::</span><span class="no">AttributeSupport</span>
      <span class="c1"># Deprecations must be required after include AttributeSupport</span>
      <span class="nb">require</span> <span class="s1">'cocoapods-core/specification/dsl/deprecations'</span>

      <span class="n">attribute</span> <span class="ss">:name</span><span class="p">,</span>
                <span class="ss">:required</span> <span class="o">=&gt;</span> <span class="kp">true</span><span class="p">,</span>
                <span class="ss">:inherited</span> <span class="o">=&gt;</span> <span class="kp">false</span><span class="p">,</span>
                <span class="ss">:multi_platform</span> <span class="o">=&gt;</span> <span class="kp">false</span>

      <span class="n">root_attribute</span> <span class="ss">:version</span><span class="p">,</span>
                      <span class="ss">:required</span> <span class="o">=&gt;</span> <span class="kp">true</span>
      <span class="c1"># ...</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>可以看出 name 和 version 的方法声明与普通的不太一样，其实 <code class="language-plaintext highlighter-rouge">attribute</code> 和 <code class="language-plaintext highlighter-rouge">root_attribute</code> 是通过 Ruby 的方法包装器来实现的，感兴趣的同学看这里 「<a href="https://github.com/mxchenxiaodong/haha_day/issues/3#">Python装饰器 与 Ruby实现</a>」。</p>

<blockquote>
  <p>Tips: Ruby 原生提供的属性访问器 — <code class="language-plaintext highlighter-rouge">attr_accessor</code> 大家应该不陌生，就是通过包装器实现的。</p>
</blockquote>

<p>这些<strong>装饰器所声明的方法会在其模块被加载时动态生成</strong>，来看其实现：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># `lib/cocoapods-core/specification/attribute_support.rb`</span>
<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Specification</span>
    <span class="k">module</span> <span class="nn">DSL</span>
      <span class="k">class</span> <span class="o">&lt;&lt;</span> <span class="nb">self</span>
        <span class="nb">attr_reader</span> <span class="ss">:attributes</span>
      <span class="k">end</span>

      <span class="k">module</span> <span class="nn">AttributeSupport</span>
        <span class="k">def</span> <span class="nf">root_attribute</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">options</span> <span class="o">=</span> <span class="p">{})</span>
          <span class="n">options</span><span class="p">[</span><span class="ss">:root_only</span><span class="p">]</span> <span class="o">=</span> <span class="kp">true</span>
          <span class="n">options</span><span class="p">[</span><span class="ss">:multi_platform</span><span class="p">]</span> <span class="o">=</span> <span class="kp">false</span>
          <span class="n">store_attribute</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
        <span class="k">end</span>

        <span class="k">def</span> <span class="nf">attribute</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">options</span> <span class="o">=</span> <span class="p">{})</span>
          <span class="n">store_attribute</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
        <span class="k">end</span>

        <span class="k">def</span> <span class="nf">store_attribute</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
          <span class="kp">attr</span> <span class="o">=</span> <span class="no">Attribute</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
          <span class="vi">@attributes</span> <span class="o">||=</span> <span class="p">{}</span>
          <span class="vi">@attributes</span><span class="p">[</span><span class="nb">name</span><span class="p">]</span> <span class="o">=</span> <span class="kp">attr</span>
        <span class="k">end</span>
      <span class="k">end</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">attribute</code> 和 <code class="language-plaintext highlighter-rouge">root_attribute</code> 最终都走到了 <code class="language-plaintext highlighter-rouge">store_attribute</code> 保存在创建的 Attribute 对象内，并以配置的 Symbol 名称作为 KEY 存入 <code class="language-plaintext highlighter-rouge">@attributes</code>，用于生成最终的 attributes setter 方法。</p>

<p>最关键的一步，让我们回到 <code class="language-plaintext highlighter-rouge">specification</code> 文件：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># `/lib/coocapods-core/specification`</span>
<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Specification</span>
    <span class="c1"># ...</span>
    
    <span class="k">def</span> <span class="nf">store_attribute</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">value</span><span class="p">,</span> <span class="n">platform_name</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
      <span class="nb">name</span> <span class="o">=</span> <span class="nb">name</span><span class="p">.</span><span class="nf">to_s</span>
      <span class="n">value</span> <span class="o">=</span> <span class="no">Specification</span><span class="p">.</span><span class="nf">convert_keys_to_string</span><span class="p">(</span><span class="n">value</span><span class="p">)</span> <span class="k">if</span> <span class="n">value</span><span class="p">.</span><span class="nf">is_a?</span><span class="p">(</span><span class="no">Hash</span><span class="p">)</span>
      <span class="n">value</span> <span class="o">=</span> <span class="n">value</span><span class="p">.</span><span class="nf">strip_heredoc</span><span class="p">.</span><span class="nf">strip</span> <span class="k">if</span> <span class="n">value</span><span class="p">.</span><span class="nf">respond_to?</span><span class="p">(</span><span class="ss">:strip_heredoc</span><span class="p">)</span>
      <span class="k">if</span> <span class="n">platform_name</span>
        <span class="n">platform_name</span> <span class="o">=</span> <span class="n">platform_name</span><span class="p">.</span><span class="nf">to_s</span>
        <span class="n">attributes_hash</span><span class="p">[</span><span class="n">platform_name</span><span class="p">]</span> <span class="o">||=</span> <span class="p">{}</span>
        <span class="n">attributes_hash</span><span class="p">[</span><span class="n">platform_name</span><span class="p">][</span><span class="nb">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
      <span class="k">else</span>
        <span class="n">attributes_hash</span><span class="p">[</span><span class="nb">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
      <span class="k">end</span>
    <span class="k">end</span>

    <span class="no">DSL</span><span class="p">.</span><span class="nf">attributes</span><span class="p">.</span><span class="nf">values</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">a</span><span class="o">|</span>
      <span class="n">define_method</span><span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="nf">writer_name</span><span class="p">)</span> <span class="k">do</span> <span class="o">|</span><span class="n">value</span><span class="o">|</span>
        <span class="n">store_attribute</span><span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="nf">name</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
      <span class="k">end</span>

      <span class="k">if</span> <span class="n">a</span><span class="p">.</span><span class="nf">writer_singular_form</span>
        <span class="kp">alias_method</span><span class="p">(</span><span class="n">a</span><span class="p">.</span><span class="nf">writer_singular_form</span><span class="p">,</span> <span class="n">a</span><span class="p">.</span><span class="nf">writer_name</span><span class="p">)</span>
      <span class="k">end</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><code class="language-plaintext highlighter-rouge">Specification</code> 类被加载时，会先遍历 <code class="language-plaintext highlighter-rouge">DSL</code> module 加载后所保存的 attributes，再通过 <code class="language-plaintext highlighter-rouge">define_method</code> 动态生成对应的配置方法。最终数据还是保存在 <code class="language-plaintext highlighter-rouge">attributes_hash</code> 中。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123416825-7fdc4274-d87a-45d0-9d04-4eeeb063c81c.png" alt="" /></p>

<h3 id="attribute">Attribute</h3>

<p>Attribute 是为了记录该配置的相关信息，例如，记录 <code class="language-plaintext highlighter-rouge">Spec</code> 是否为根节点、<code class="language-plaintext highlighter-rouge">Spec</code> 类型、所支持的 platforms、资源地址通配符等。</p>

<ol>
  <li>以 <code class="language-plaintext highlighter-rouge">root_attribute</code> 包装的配置仅用于修饰 <code class="language-plaintext highlighter-rouge">Spec</code> 根节点，比如版本号 <code class="language-plaintext highlighter-rouge">version</code> 只能由 <code class="language-plaintext highlighter-rouge">Spec</code> 根节点来设置，另外还有 <code class="language-plaintext highlighter-rouge">source</code>、<code class="language-plaintext highlighter-rouge">static_framework</code>、<code class="language-plaintext highlighter-rouge">module_name</code> 等；</li>
  <li>以 <code class="language-plaintext highlighter-rouge">attribute</code> 包装的配置则不限是否为 <code class="language-plaintext highlighter-rouge">Spec</code> 根结点。我们以 AFNetworking 的 <code class="language-plaintext highlighter-rouge">source_files</code> 为例：由于在 macOS 和 watchOS 上并没有 UIKit framwork，因此它单独将 UIKit 的相关功能拆分到了 <code class="language-plaintext highlighter-rouge">AFNetworking/UIKit</code> 中；</li>
</ol>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">Pod</span><span class="o">::</span><span class="no">Spec</span><span class="p">.</span><span class="nf">new</span> <span class="k">do</span> <span class="o">|</span><span class="n">s</span><span class="o">|</span>
  <span class="c1"># ...</span>
  <span class="n">s</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'NSURLSession'</span> <span class="k">do</span> <span class="o">|</span><span class="n">ss</span><span class="o">|</span>
	 <span class="c1"># ...</span>
  <span class="k">end</span>

  <span class="n">s</span><span class="p">.</span><span class="nf">subspec</span> <span class="s1">'UIKit'</span> <span class="k">do</span> <span class="o">|</span><span class="n">ss</span><span class="o">|</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">ios</span><span class="p">.</span><span class="nf">deployment_target</span> <span class="o">=</span> <span class="s1">'9.0'</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">tvos</span><span class="p">.</span><span class="nf">deployment_target</span> <span class="o">=</span> <span class="s1">'9.0'</span>
    <span class="n">ss</span><span class="p">.</span><span class="nf">dependency</span> <span class="s1">'AFNetworking/NSURLSession'</span>

    <span class="n">ss</span><span class="p">.</span><span class="nf">source_files</span> <span class="o">=</span> <span class="s1">'UIKit+AFNetworking'</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<h3 id="subspec">#subspec</h3>

<p>除了 attribute 装饰器声明的 setter 方法，还有几个自定义的方法是直接通过 eval 调用的。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">subspec</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">subspec</span> <span class="o">=</span> <span class="no">Specification</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="nb">self</span><span class="p">,</span> <span class="nb">name</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="vi">@subspecs</span> <span class="o">&lt;&lt;</span> <span class="n">subspec</span>
  <span class="n">subspec</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">test_spec</span><span class="p">(</span><span class="nb">name</span> <span class="o">=</span> <span class="s1">'Tests'</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">subspec</span> <span class="o">=</span> <span class="no">Specification</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="nb">self</span><span class="p">,</span> <span class="nb">name</span><span class="p">,</span> <span class="kp">true</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="vi">@subspecs</span> <span class="o">&lt;&lt;</span> <span class="n">subspec</span>
  <span class="n">subspec</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">app_spec</span><span class="p">(</span><span class="nb">name</span> <span class="o">=</span> <span class="s1">'App'</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="n">appspec</span> <span class="o">=</span> <span class="no">Specification</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="nb">self</span><span class="p">,</span> <span class="nb">name</span><span class="p">,</span> <span class="ss">:app_specification</span> <span class="o">=&gt;</span> <span class="kp">true</span><span class="p">,</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
  <span class="vi">@subspecs</span> <span class="o">&lt;&lt;</span> <span class="n">appspec</span>
  <span class="n">appspec</span>
<span class="k">end</span>
</code></pre></div></div>

<p>这三种不同类型的 <code class="language-plaintext highlighter-rouge">Subspec</code> 经 <code class="language-plaintext highlighter-rouge">eval</code> 转换为对应的 <code class="language-plaintext highlighter-rouge">Specification</code> 对象，注意这里初始化后都将 parent 节点指向 <strong>self</strong> 同时存入 <code class="language-plaintext highlighter-rouge">@subspecs</code> 数组中，完成 <code class="language-plaintext highlighter-rouge">SubSpec</code> 依赖链的构造。</p>

<h3 id="dependency">#dependency</h3>

<p>对于其他 <code class="language-plaintext highlighter-rouge">pod</code> 依赖的添加我们通过 dependency 方法来实现：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">dependency</span><span class="p">(</span><span class="o">*</span><span class="n">args</span><span class="p">)</span>
  <span class="nb">name</span><span class="p">,</span> <span class="o">*</span><span class="n">version_requirements</span> <span class="o">=</span> <span class="n">args</span>
  <span class="c1"># dependency args 有效性校验 ...</span>

  <span class="n">attributes_hash</span><span class="p">[</span><span class="s1">'dependencies'</span><span class="p">]</span> <span class="o">||=</span> <span class="p">{}</span>
  <span class="n">attributes_hash</span><span class="p">[</span><span class="s1">'dependencies'</span><span class="p">][</span><span class="nb">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">version_requirements</span>

  <span class="k">unless</span> <span class="n">whitelisted_configurations</span><span class="p">.</span><span class="nf">nil?</span>
    <span class="c1"># configuration 白名单过滤和校验 ...</span>

    <span class="n">attributes_hash</span><span class="p">[</span><span class="s1">'configuration_pod_whitelist'</span><span class="p">]</span> <span class="o">||=</span> <span class="p">{}</span>
    <span class="n">attributes_hash</span><span class="p">[</span><span class="s1">'configuration_pod_whitelist'</span><span class="p">][</span><span class="nb">name</span><span class="p">]</span> <span class="o">=</span> <span class="n">whitelisted_configurations</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p>dependency 方法内部主要是对依赖有效性的校验，限于篇幅这里不列出实现，核心要点如下：</p>

<ol>
  <li><strong>检查依赖循环</strong>，根据 <code class="language-plaintext highlighter-rouge">Spec</code> 名称判断 <code class="language-plaintext highlighter-rouge">Spec</code> 与自身，<code class="language-plaintext highlighter-rouge">Spec</code> 与<code class="language-plaintext highlighter-rouge">SubSpec</code>之间是否存在循环依赖；</li>
  <li><strong>检查依赖来源</strong>，<code class="language-plaintext highlighter-rouge">Podspec</code> 中不支持 <code class="language-plaintext highlighter-rouge">:git</code> 或 <code class="language-plaintext highlighter-rouge">:path</code> 形式的来源指定，如需设定可通过 <code class="language-plaintext highlighter-rouge">Podfile</code> 来修改;</li>
  <li><strong>检查 configuation 白名单</strong>，目前仅支持 Xcode 默认的 <code class="language-plaintext highlighter-rouge">Debug</code> 和 <code class="language-plaintext highlighter-rouge">Release</code> 的 configuration 配置；</li>
</ol>

<h1 id="创建并使用你的-pod">创建并使用你的 Pod</h1>

<p>最后一节来两个实践：创建 Pod 以及在项目中使用 <code class="language-plaintext highlighter-rouge">SubSpecs</code>。</p>

<h2 id="pod-创建">Pod 创建</h2>

<p>pod 相关使用官方都提供了很详尽的都文档，本小节仅做介绍。</p>

<h3 id="1-创建-pod">1. 创建 Pod</h3>

<p>仅需一行命令完成 <code class="language-plaintext highlighter-rouge">Pod</code> 创建（<a href="https://guides.cocoapods.org/making/using-pod-lib-create.html">文档</a>）：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>pod lib create <span class="sb">`</span>NAME<span class="sb">`</span>
</code></pre></div></div>

<p>之后每一步都会输出友好提示，按照提示选择即可。在添加完 source code 和 dependency 之后，你还可以在 CocoaPods 为你提供的 Example 项目中运行和调试代码。</p>

<p>准备就绪后，可以通过以下命令进行校验，检查 <code class="language-plaintext highlighter-rouge">Pod</code> 正确性：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>pod lib lint <span class="sb">`</span><span class="o">[</span>Podspec_PATHS ...]<span class="sb">`</span>
</code></pre></div></div>

<h3 id="2-发布-pod">2. 发布 Pod</h3>

<p>校验通过后就可以将 <code class="language-plaintext highlighter-rouge">Pod</code> 发布了，你可以将 <code class="language-plaintext highlighter-rouge">PodSepc</code> 发布到  Master Repo 上，或者发布到内部的 Spec Repo 上。</p>

<p><strong>CocoaPods Master Repo</strong></p>

<p>如果发布的 CocoaPods 的主仓库，那么需要通过 CocoaPods 提供的 <strong>Trunk</strong> 命令：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>pod trunk push <span class="sb">`</span><span class="o">[</span>NAME.podspec]<span class="sb">`</span>
</code></pre></div></div>

<p>不过使用前需要先通过邮箱注册，详情查看<a href="https://guides.cocoapods.org/making/getting-setup-with-trunk.html">文档</a>。</p>

<p><strong>Private Spec Repo</strong></p>

<p>对于发布到私有仓库的，可通过 CocoaPods 提供的 <strong>Repo</strong> 命令：</p>

<div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nv">$ </span>pod repo push <span class="sb">`</span>REPO_NAME<span class="sb">`</span> <span class="sb">`</span>SPEC_NAME.podspec<span class="sb">`</span>
</code></pre></div></div>

<p>文档详情 — <a href="https://guides.cocoapods.org/making/private-cocoapods.html">传送门</a>。</p>

<h2 id="subspecs-in-podfile">SubSpecs In Podfile</h2>

<p>在 <code class="language-plaintext highlighter-rouge">SubSpec</code> 一节提到过，在 CocoaPods 中 <code class="language-plaintext highlighter-rouge">SubSpec</code> 是被作为单独的依赖来看待的，这里就借这个实操来证明一下。</p>

<p>在上文的实践中，我们知道每一个 <code class="language-plaintext highlighter-rouge">Pod</code> 库对应为 Xcode 项目中的一个个 target，那么当明确指定部分 <code class="language-plaintext highlighter-rouge">SubSpec</code> 时，它们也将被作为独立的 target 进行编译。不过这里需要明确一下使用场景：</p>

<h3 id="1-single-target">1. Single Target</h3>

<p>当主项目中仅有一个 target 或多个 target 引用了同一个 <code class="language-plaintext highlighter-rouge">pod</code> 库的多个不同 <code class="language-plaintext highlighter-rouge">SubSpec</code> 时，生成的 target 只会有一个。我们以 QMUIKit 为例，项目 Demo.project 下的 Podfile 配置如下：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">target</span> <span class="s1">'Demo'</span> <span class="k">do</span>
  <span class="n">pod</span> <span class="s1">'QMUIKit/QMUIComponents/QMUILabel'</span><span class="p">,</span> <span class="ss">:path</span> <span class="o">=&gt;</span> <span class="s1">'../QMUI_iOS'</span>
  <span class="n">pod</span> <span class="s1">'QMUIKit/QMUIComponents/QMUIButton'</span><span class="p">,</span> <span class="ss">:path</span> <span class="o">=&gt;</span> <span class="s1">'../QMUI_iOS'</span>
<span class="k">end</span>
</code></pre></div></div>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123432109-ac15c4c8-89fd-4547-bbd0-704681fa8d77.png" alt="" /></p>

<p>此时 <code class="language-plaintext highlighter-rouge">Pods.project</code> 下的 QMUIKit 的 target 名称为 <strong>QMUIKit</strong>。</p>

<h3 id="2-multiple-target">2. Multiple Target</h3>

<p>如果我们的主项目中存在多个 target 且使用同一个 <code class="language-plaintext highlighter-rouge">pod</code> 库的不同 <code class="language-plaintext highlighter-rouge">SubSpec</code> 时，结果则有所不同。</p>

<p>现在我们在步骤 1 的基础上添加如下配置：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">target</span> <span class="s1">'Demo2'</span> <span class="k">do</span>
	<span class="n">pod</span> <span class="s1">'QMUIKit/QMUIComponents/QMUILog'</span><span class="p">,</span> <span class="ss">:path</span> <span class="o">=&gt;</span> <span class="s1">'../QMUI_iOS'</span>
<span class="k">end</span>
</code></pre></div></div>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602123439862-d2a9f0e9-7177-4714-8914-364c5c77e18a.png" alt="" /></p>

<p>可以发现，CocoaPods 为每个 tareget 对应的 <code class="language-plaintext highlighter-rouge">SubSpec</code> 依赖生成了不同的 QMUIKit targets。</p>

<blockquote>
  <p>Tips: 当主工程 target 依赖的 <code class="language-plaintext highlighter-rouge">Subspec</code> 数量过多导致的名称超过 50 个字符，将会对 subspec 后缀做摘要处理作为唯一标识符。</p>
</blockquote>

<h1 id="总结">总结</h1>

<p>本文是 CocoaPods-Core 的第二篇，重点介绍了 <code class="language-plaintext highlighter-rouge">Podspec</code> 的类构成和解析实现，总结如下：</p>

<ol>
  <li>初探 <code class="language-plaintext highlighter-rouge">Podspec</code> 让我们对其能力边界和配置分类有了更好的了解；</li>
  <li>深入 <code class="language-plaintext highlighter-rouge">Podspec</code> 我们发现其数据结构同 <code class="language-plaintext highlighter-rouge">Podfile</code> 类似，都是根据依赖关系建立对应的树结构；</li>
  <li><code class="language-plaintext highlighter-rouge">Podspec</code> 针对单个库的源码和资源提供了更精细化的管理，<code class="language-plaintext highlighter-rouge">SubSpec</code> 结构的推出让大型 library 的内部分层提供了很好的工具；</li>
  <li>装饰器模式结合 Ruby 的动态特性，让 <code class="language-plaintext highlighter-rouge">Podspec</code> 的 DSL 特性的实现起来更加优雅；</li>
</ol>

<h1 id="知识点问题梳理">知识点问题梳理</h1>

<p>这里罗列了四个问题用来考察你是否已经掌握了这篇文章，如果没有建议你加入**收藏 **再次阅读：</p>

<ol>
  <li>说说 <code class="language-plaintext highlighter-rouge">Podspec</code> 所支持的配置有几类，分别具有哪些功能 ？</li>
  <li><code class="language-plaintext highlighter-rouge">Podspec</code> 与 <code class="language-plaintext highlighter-rouge">SubSpec</code> 之间有哪些关系 ？</li>
  <li>说说 <code class="language-plaintext highlighter-rouge">SubSpec</code> 的特点以及作用 ？</li>
  <li>谈谈 <code class="language-plaintext highlighter-rouge">Podspec</code> 中的 DSL 解析与 <code class="language-plaintext highlighter-rouge">Podfile</code> 的解析实现有哪些区别 ？</li>
</ol>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="CocoaPods 历险记" /><category term="Ruby" /><summary type="html"><![CDATA[引子 在上文 Podfile 解析逻辑 中（建议先阅读这篇文章），我们以 Xcode 工程结构作为切入点介绍了 Podfile 背后对应的数据结构，剖析了 Podfile 文件是如何解析与加载，并最终 “入侵” 项目影响其工程结构的。今天我们来聊一聊 CocoaPods-Core 中的另一个重要文件 — Podspec 以及它所撑起的 CocoaPods 世界。 一个 Pod 的创建和发布离不开 .podspec 文件，它可以很简单也能复杂，如 QMUIKit（后续介绍)。 今天我们就直奔主题，来分析 Podspec 文件。 Podspec Podspec 是用于 描述一个 Pod 库的源代码和资源将如何被打包编译成链接库或 framework 的文件 ，而 Podspec 中的这些描述内容最终将映会映射到 Specification 类中（以下简称 Spec）。 现在让我们来重新认识 Podspec。 Podspec 初探 Podspec 支持的文件格式为 .podspec 和 .json 两种，而 .podspec 本质是 Ruby 文件。 问题来了，为什么是 JSON 格式而不像 Podfile 一样支持 YAML 呢？ 笔者的理解：由于 Podspec 文件会满世界跑，它可能存在于 CocoaPods 的 CDN Service、Speces Repo 或者你们的私有 Specs Repo 上，因此采用  JSON 的文件在网络传输中会更友好。而 Podfile 更多的场景是用于序列化，它需要在项目中生成一份经依赖仲裁后的 Podfile 快照，用于后续的对比。 Podspec Pod::Spec.new do |spec| spec.name = 'Reachability' spec.version = '3.1.0' spec.license = { :type =&gt; 'BSD' } spec.homepage = 'https://github.com/tonymillion/Reachability' spec.authors = { 'Tony Million' =&gt; 'tonymillion@gmail.com' } spec.summary = 'ARC and GCD Compatible Reachability Class for iOS and OS X.' spec.source = { :git =&gt; 'https://github.com/tonymillion/Reachability.git', :tag =&gt; "v#{spec.version}" } spec.source_files = 'Reachability.{h,m}' spec.framework = 'SystemConfiguration' end 上面这份 Reachability.podspec 配置，基本通过命令行 pod lib create NAME 就能帮我们完成。除此之外我们能做的更多，比如，默认情况下 CococaPods 会为每个 Pod framework 生成一个对应的 modulemap 文件，它将包含 Podspec 中指定的公共 headers。如果需要自定义引入的 header 文件，仅需配置 moduel_map 即可完成。 下面是进阶版配置： Pod::Spec.new do |spec| spec.name = 'Reachability' # 省略与前面相同部分的配置 ... spec.module_name = 'Rich' spec.swift_version = '4.0' spec.ios.deployment_target = '9.0' spec.osx.deployment_target = '10.10' spec.source_files = 'Reachability/common/*.swift' spec.ios.source_files = 'Reachability/ios/*.swift', 'Reachability/extensions/*.swift' spec.osx.source_files = 'Reachability/osx/*.swift' spec.framework = 'SystemConfiguration' spec.ios.framework = 'UIKit' spec.osx.framework = 'AppKit' spec.dependency 'SomeOtherPod' end 像 👆 我们为不同的系统指定了不同的源码和依赖等，当然可配置的不只这些。 Podspec 支持的完整配置分类如下： 想了解更多的配置选项：传送门。 Convention Over Configuration 说到配置，不得不提一下 CoC 约定大于配置。约定大于配置算是在软件工程较早出现的概念的了，大意是：为了简单起见，我们的代码需要按照一定的约定来编写（如代码放在什么目录，用什么文件名，用什么类名等)。 这样既简化了配置文件，同时也降低了学习成本。 约定大于配置可以说是通过 Ruby on Rails 发扬光大的。尽管它一直饱受争议，但是主流语言的依赖管理工具，如 Maven、npm 等都遵循 CoC 进行不断演进的，因为 CoC 能够有效帮助开发者减轻选择的痛感，减少无意义的选择。一些新的语言也吸收了这个思想，比如 Go 语言。如果用 C/C++ 可能需要定义复杂的 Makefile 来定义编译的规则，以及如何运行测试用例，而在 Go 中这些都是约定好的。 举个 🌰 ：Podfile 中是可以指定 pod library 所链接的 Xcode project，不过大多情况下无需配置，CocoaPods 会自动查找 Podfile 所在的同级目录下所对应的工程文件 .project 。 Spec 的核心数据结构 Specification 在数据结构上 Specification 与 TargetDefinition 是类似的，同为多叉树结构。简化后的 Spec 的类如下： require 'active_support/core_ext/string/strip.rb' # 记录对应 platform 上 Spec 的其他 pod 依赖 require 'cocoapods-core/specification/consumer' # 解析 DSL require 'cocoapods-core/specification/dsl' # 校验 Spec 的正确性，并抛出对应的错误和警告 require 'cocoapods-core/specification/linter' # 用于解析 DSL 内容包含的配置信息 require 'cocoapods-core/specification/root_attribute_accessors' # 记录一个 Pod 所有依赖的 Spec 来源信息 require 'cocoapods-core/specification/set' # json 格式数据解析 require 'cocoapods-core/specification/json' module Pod class Specification include Pod::Specification::DSL include Pod::Specification::DSL::Deprecations include Pod::Specification::RootAttributesAccessors include Pod::Specification::JSONSupport # `subspec` 的父节点 attr_reader :parent # `Spec` 的唯一 id，由 name + version 的 hash 构成 attr_reader :hash_value # 记录 `Spec` 的配置信息 attr_accessor :attributes_hash # `Spec` 包含的 `subspec` attr_accessor :subspecs # 递归调用获取 Specification 的根节点 def root parent ? parent.root : self end def hash if @hash_value.nil? @hash_value = (name.hash * 53) ^ version.hash end @hash_value end # ... end end Specification 同样用 map attributes_hash 来记录配置信息。 注意，这里的 parent 是为 subspec 保留的，用于指向其父节点的 Spec。 Subspecs 乍一听 Subspec 这个概念似乎有一些抽象，不过当你理解了上面的描述，就能明白什么是 Subspec 了。我们知道在 Xcode 项目中，target 作为最小的可编译单元，它编译后的产物为链接库或 framework。而在 CocoaPods 的世界里这些 targets 则是由 Spec 文件来描述的，它还能拆分成一个或者多个 Subspec，我们暂且把它称为 Spec 的 子模块，子模块也是用 Specification 类来描述的。 子模块可以单独作为依赖被引入到项目中。它有几个特点： 未指定 default_subspec 的情况下，Spec 的全部子模块都将作为依赖被引入； 子模块会主动继承其父节点 Spec 中定义的 attributes_hash； 子模块可以指定自己的源代码、资源文件、编译配置、依赖等； 同一 Spec 内部的子模块是可以有依赖关系的； 每个子模块在 pod push 的时候是需要被 lint 通过的； 光听总结似乎还是云里雾里，祭出 QMUI 让大家感受一下： Pod::Spec.new do |s| s.name = "QMUIKit" s.version = "4.2.1" # ... s.subspec 'QMUICore' do |ss| ss.source_files = 'QMUIKit/QMUIKit.h', 'QMUIKit/QMUICore', 'QMUIKit/UIKitExtensions' ss.dependency 'QMUIKit/QMUIWeakObjectContainer' ss.dependency 'QMUIKit/QMUILog' end s.subspec 'QMUIWeakObjectContainer' do |ss| ss.source_files = 'QMUIKit/QMUIComponents/QMUIWeakObjectContainer.{h,m}' end s.subspec 'QMUILog' do |ss| ss.source_files = 'QMUIKit/QMUIComponents/QMUILog/*.{h,m}' end s.subspec 'QMUIComponents' do |ss| ss.dependency 'QMUIKit/QMUICore' ss.subspec 'QMUIButton' do |sss| sss.source_files = 'QMUIKit/QMUIComponents/QMUIButton/QMUIButton.{h,m}' end # 此处省略 59 个 Components end # ... end 不吹不黑，QMUI 是笔者见过国内开源作品中代码注释非常详尽且提供完整 Demo 的项目之一。 整个 QMUIKit 的 Spec 文件中，总共定义了 64 个 subspec 子模块，同时这些子模块之间还做了分层。比如 QMUICore： 另外补充一点，CocoaPods 支持了不同类型的 SubSpec： # lib/cocoapods-core/specification/dsl/attribute_support.rb SUPPORTED_SPEC_TYPES = [:library, :app, :test].freeze :app 和 :test 用于在项目中集成单元测试代码的 Subspec。 Podspec From JSON 有了上文 Podfile 的了解，这次我们对 Podspec 的文件加载会更加轻车熟路。首先是由 #from_file 方法进行文件路径和内容编码格式的检查，将加载的内容转入 #from_string： def self.from_file(path, subspec_name = nil) path = Pathname.new(path) unless path.exist? raise Informative, "No Podspec exists at path `#{path}`." end string = File.open(path, 'r:utf-8', &amp;:read) # Work around for Rubinius incomplete encoding in 1.9 mode if string.respond_to?(:encoding) &amp;&amp; string.encoding.name != 'UTF-8' string.encode!('UTF-8') end from_string(string, path, subspec_name) end def self.from_string(spec_contents, path, subspec_name = nil) path = Pathname.new(path).expand_path spec = nil case path.extname when '.podspec' Dir.chdir(path.parent.directory? ? path.parent : Dir.pwd) do spec = ::Pod._eval_Podspec(spec_contents, path) unless spec.is_a?(Specification) raise Informative, "Invalid Podspec file at path `#{path}`." end end when '.json' spec = Specification.from_json(spec_contents) else raise Informative, "Unsupported specification format `#{path.extname}` for spec at `#{path}`." end spec.defined_in_file = path spec.subspec_by_name(subspec_name, true) end 接着根据文件类型为 .podspec 和 .json 分别采用不同的解析方式。在  JSONSupport 模块内将 #from_json 的逻辑拆成了两部分： # `lib/cocoapods-core/specification/json.rb` module Pod class Specification module JSONSupport # ① def self.from_json(json) require 'json' hash = JSON.parse(json) from_hash(hash) end # ② def self.from_hash(hash, parent = nil, test_specification: false, app_specification: false) attributes_hash = hash.dup spec = Spec.new(parent, nil, test_specification, :app_specification =&gt; app_specification) subspecs = attributes_hash.delete('subspecs') testspecs = attributes_hash.delete('testspecs') appspecs = attributes_hash.delete('appspecs') ## backwards compatibility with 1.3.0 spec.test_specification = !attributes_hash['test_type'].nil? spec.attributes_hash = attributes_hash spec.subspecs.concat(subspecs_from_hash(spec, subspecs, false, false)) spec.subspecs.concat(subspecs_from_hash(spec, testspecs, true, false)) spec.subspecs.concat(subspecs_from_hash(spec, appspecs, false, true)) spec end # ③ def self.subspecs_from_hash(spec, subspecs, test_specification, app_specification) return [] if subspecs.nil? subspecs.map do |s_hash| Specification.from_hash(s_hash, spec, :test_specification =&gt; test_specification, :app_specification =&gt; app_specification) end end end end 这里的逻辑也是比较简单： ① 将传入的字符串转换为 json； ② 将转换后的 json 转换为 Spec 对象并将 json 转换为 attributes_hash，同时触发 ③； ③ 通过 self.subspecs_from_hash 实现递归调用完成 subspecs 解析； Tips: 方法 ② 里的 Spec 是对 Specification 的别名。 Podspec From Ruby QMUIKit.podspec 的文件内容，大家是否注意到其开头的声明： Pod::Spec.new do |s| s.name = "QMUIKit" s.source_files = 'QMUIKit/QMUIKit.h' # ... end 发现没 .podspec 文件就是简单直接地声明了一个 Specifiction 对象，然后通过 block 块定制来完成配置。像 name、source_files 这些配置参数最终都会转换为方法调用并将值存入 attributes_hash 中。这些方法调用的实现方式分两种： 大部分配置是通过方法包装器 attribute 和 root_attribute 来动态添加的 setter 方法； 对于复杂逻辑的配置则直接方法声明，如 subspec 、dependency 方法等（后续介绍)。 attribute wrappter # `lib/cocoapods-core/specification/dsl.rb` module Pod class Specification module DSL extend Pod::Specification::DSL::AttributeSupport # Deprecations must be required after include AttributeSupport require 'cocoapods-core/specification/dsl/deprecations' attribute :name, :required =&gt; true, :inherited =&gt; false, :multi_platform =&gt; false root_attribute :version, :required =&gt; true # ... end end end 可以看出 name 和 version 的方法声明与普通的不太一样，其实 attribute 和 root_attribute 是通过 Ruby 的方法包装器来实现的，感兴趣的同学看这里 「Python装饰器 与 Ruby实现」。 Tips: Ruby 原生提供的属性访问器 — attr_accessor 大家应该不陌生，就是通过包装器实现的。 这些装饰器所声明的方法会在其模块被加载时动态生成，来看其实现： # `lib/cocoapods-core/specification/attribute_support.rb` module Pod class Specification module DSL class &lt;&lt; self attr_reader :attributes end module AttributeSupport def root_attribute(name, options = {}) options[:root_only] = true options[:multi_platform] = false store_attribute(name, options) end def attribute(name, options = {}) store_attribute(name, options) end def store_attribute(name, options) attr = Attribute.new(name, options) @attributes ||= {} @attributes[name] = attr end end end end end attribute 和 root_attribute 最终都走到了 store_attribute 保存在创建的 Attribute 对象内，并以配置的 Symbol 名称作为 KEY 存入 @attributes，用于生成最终的 attributes setter 方法。 最关键的一步，让我们回到 specification 文件： # `/lib/coocapods-core/specification` module Pod class Specification # ... def store_attribute(name, value, platform_name = nil) name = name.to_s value = Specification.convert_keys_to_string(value) if value.is_a?(Hash) value = value.strip_heredoc.strip if value.respond_to?(:strip_heredoc) if platform_name platform_name = platform_name.to_s attributes_hash[platform_name] ||= {} attributes_hash[platform_name][name] = value else attributes_hash[name] = value end end DSL.attributes.values.each do |a| define_method(a.writer_name) do |value| store_attribute(a.name, value) end if a.writer_singular_form alias_method(a.writer_singular_form, a.writer_name) end end end end Specification 类被加载时，会先遍历 DSL module 加载后所保存的 attributes，再通过 define_method 动态生成对应的配置方法。最终数据还是保存在 attributes_hash 中。 Attribute Attribute 是为了记录该配置的相关信息，例如，记录 Spec 是否为根节点、Spec 类型、所支持的 platforms、资源地址通配符等。 以 root_attribute 包装的配置仅用于修饰 Spec 根节点，比如版本号 version 只能由 Spec 根节点来设置，另外还有 source、static_framework、module_name 等； 以 attribute 包装的配置则不限是否为 Spec 根结点。我们以 AFNetworking 的 source_files 为例：由于在 macOS 和 watchOS 上并没有 UIKit framwork，因此它单独将 UIKit 的相关功能拆分到了 AFNetworking/UIKit 中； Pod::Spec.new do |s| # ... s.subspec 'NSURLSession' do |ss| # ... end s.subspec 'UIKit' do |ss| ss.ios.deployment_target = '9.0' ss.tvos.deployment_target = '9.0' ss.dependency 'AFNetworking/NSURLSession' ss.source_files = 'UIKit+AFNetworking' end end #subspec 除了 attribute 装饰器声明的 setter 方法，还有几个自定义的方法是直接通过 eval 调用的。 def subspec(name, &amp;block) subspec = Specification.new(self, name, &amp;block) @subspecs &lt;&lt; subspec subspec end def test_spec(name = 'Tests', &amp;block) subspec = Specification.new(self, name, true, &amp;block) @subspecs &lt;&lt; subspec subspec end def app_spec(name = 'App', &amp;block) appspec = Specification.new(self, name, :app_specification =&gt; true, &amp;block) @subspecs &lt;&lt; appspec appspec end 这三种不同类型的 Subspec 经 eval 转换为对应的 Specification 对象，注意这里初始化后都将 parent 节点指向 self 同时存入 @subspecs 数组中，完成 SubSpec 依赖链的构造。 #dependency 对于其他 pod 依赖的添加我们通过 dependency 方法来实现： def dependency(*args) name, *version_requirements = args # dependency args 有效性校验 ... attributes_hash['dependencies'] ||= {} attributes_hash['dependencies'][name] = version_requirements unless whitelisted_configurations.nil? # configuration 白名单过滤和校验 ... attributes_hash['configuration_pod_whitelist'] ||= {} attributes_hash['configuration_pod_whitelist'][name] = whitelisted_configurations end end dependency 方法内部主要是对依赖有效性的校验，限于篇幅这里不列出实现，核心要点如下： 检查依赖循环，根据 Spec 名称判断 Spec 与自身，Spec 与SubSpec之间是否存在循环依赖； 检查依赖来源，Podspec 中不支持 :git 或 :path 形式的来源指定，如需设定可通过 Podfile 来修改; 检查 configuation 白名单，目前仅支持 Xcode 默认的 Debug 和 Release 的 configuration 配置； 创建并使用你的 Pod 最后一节来两个实践：创建 Pod 以及在项目中使用 SubSpecs。 Pod 创建 pod 相关使用官方都提供了很详尽的都文档，本小节仅做介绍。 1. 创建 Pod 仅需一行命令完成 Pod 创建（文档）： $ pod lib create `NAME` 之后每一步都会输出友好提示，按照提示选择即可。在添加完 source code 和 dependency 之后，你还可以在 CocoaPods 为你提供的 Example 项目中运行和调试代码。 准备就绪后，可以通过以下命令进行校验，检查 Pod 正确性： $ pod lib lint `[Podspec_PATHS ...]` 2. 发布 Pod 校验通过后就可以将 Pod 发布了，你可以将 PodSepc 发布到  Master Repo 上，或者发布到内部的 Spec Repo 上。 CocoaPods Master Repo 如果发布的 CocoaPods 的主仓库，那么需要通过 CocoaPods 提供的 Trunk 命令： $ pod trunk push `[NAME.podspec]` 不过使用前需要先通过邮箱注册，详情查看文档。 Private Spec Repo 对于发布到私有仓库的，可通过 CocoaPods 提供的 Repo 命令： $ pod repo push `REPO_NAME` `SPEC_NAME.podspec` 文档详情 — 传送门。 SubSpecs In Podfile 在 SubSpec 一节提到过，在 CocoaPods 中 SubSpec 是被作为单独的依赖来看待的，这里就借这个实操来证明一下。 在上文的实践中，我们知道每一个 Pod 库对应为 Xcode 项目中的一个个 target，那么当明确指定部分 SubSpec 时，它们也将被作为独立的 target 进行编译。不过这里需要明确一下使用场景： 1. Single Target 当主项目中仅有一个 target 或多个 target 引用了同一个 pod 库的多个不同 SubSpec 时，生成的 target 只会有一个。我们以 QMUIKit 为例，项目 Demo.project 下的 Podfile 配置如下： target 'Demo' do pod 'QMUIKit/QMUIComponents/QMUILabel', :path =&gt; '../QMUI_iOS' pod 'QMUIKit/QMUIComponents/QMUIButton', :path =&gt; '../QMUI_iOS' end 此时 Pods.project 下的 QMUIKit 的 target 名称为 QMUIKit。 2. Multiple Target 如果我们的主项目中存在多个 target 且使用同一个 pod 库的不同 SubSpec 时，结果则有所不同。 现在我们在步骤 1 的基础上添加如下配置： target 'Demo2' do pod 'QMUIKit/QMUIComponents/QMUILog', :path =&gt; '../QMUI_iOS' end 可以发现，CocoaPods 为每个 tareget 对应的 SubSpec 依赖生成了不同的 QMUIKit targets。 Tips: 当主工程 target 依赖的 Subspec 数量过多导致的名称超过 50 个字符，将会对 subspec 后缀做摘要处理作为唯一标识符。 总结 本文是 CocoaPods-Core 的第二篇，重点介绍了 Podspec 的类构成和解析实现，总结如下： 初探 Podspec 让我们对其能力边界和配置分类有了更好的了解； 深入 Podspec 我们发现其数据结构同 Podfile 类似，都是根据依赖关系建立对应的树结构； Podspec 针对单个库的源码和资源提供了更精细化的管理，SubSpec 结构的推出让大型 library 的内部分层提供了很好的工具； 装饰器模式结合 Ruby 的动态特性，让 Podspec 的 DSL 特性的实现起来更加优雅； 知识点问题梳理 这里罗列了四个问题用来考察你是否已经掌握了这篇文章，如果没有建议你加入**收藏 **再次阅读： 说说 Podspec 所支持的配置有几类，分别具有哪些功能 ？ Podspec 与 SubSpec 之间有哪些关系 ？ 说说 SubSpec 的特点以及作用 ？ 谈谈 Podspec 中的 DSL 解析与 Podfile 的解析实现有哪些区别 ？]]></summary></entry><entry><title type="html">Ruby 黑魔法 - eval 和 alias</title><link href="https://www.desgard.com/2020/10/08/cocoapods-story-ex-2.html" rel="alternate" type="text/html" title="Ruby 黑魔法 - eval 和 alias" /><published>2020-10-08T00:00:00-08:00</published><updated>2020-10-08T00:00:00-08:00</updated><id>https://www.desgard.com/2020/10/08/cocoapods-story-ex-2</id><content type="html" xml:base="https://www.desgard.com/2020/10/08/cocoapods-story-ex-2.html"><![CDATA[<p>CocoaPods 是使用 Ruby 这门脚本语言实现的工具。Ruby 有很多优质的特性被 CocoaPods 所利用，为了在后续的源码阅读中不会被这些用法阻塞，所以在这个系列中，会给出一些 CocoaPods 的番外篇，来介绍 Ruby 及其当中的一些语言思想。</p>

<p>今天这一篇我们来聊聊 Ruby 中的一些十分“动态”的特性：<strong>eval 特性和 alias 特性</strong>。</p>

<h1 id="说说-eval-特性">说说 Eval 特性</h1>

<h2 id="源自-lisp-的-evaluation">源自 Lisp 的 Evaluation</h2>

<p>在一些语言中，<code class="language-plaintext highlighter-rouge">eval</code> 方法是<strong>将一个字符串当作表达式执行而返回一个结果的方法</strong>；在另外一些中，<code class="language-plaintext highlighter-rouge">eval</code> 它所传入的不一定是字符串，还有可能是抽象句法形势，Lisp 就是这种语言，并且 Lisp 也是首先提出使用 <code class="language-plaintext highlighter-rouge">eval</code> 方法的语言，并提出了 Evaluation 这个特性。<strong>这也使得 Lisp 这门语言可以实现脱离编译这套体系而动态执行的结果</strong>。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia20201009091350.png" alt="" /></p>

<p>Lisp 中的 <code class="language-plaintext highlighter-rouge">eval</code> 方法预期是：<strong>将表达式作为参数传入到 <code class="language-plaintext highlighter-rouge">eval</code> 方法，并声明给定形式的返回值，运行时动态计算</strong>。</p>

<p>下面是一个 Lisp Evaluation 代码的例子（ <a href="https://zh.wikipedia.org/wiki/Scheme">Scheme</a> 方言 RRS 及以后版本）：</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">;</span> <span class="n">将</span> <span class="n">f1</span> <span class="n">设置为表达式</span> <span class="p">(</span><span class="o">+</span> <span class="mi">1</span> <span class="mi">2</span> <span class="mi">3</span><span class="p">)</span>
<span class="p">(</span><span class="n">define</span> <span class="n">f1</span> <span class="s">'(+ 1 2 3))
 
; 执行 f1 (+ 1 2 3) 这个表达式，并返回 6
(eval f1 user-initial-environment)
</span></code></pre></div></div>

<p>可能你会觉得：<strong>这只是一个简单的特性，为什么会称作黑魔法特性？</strong></p>

<p>因为 Evaluation 这种可 eval 特性是很多思想、落地工具的基础。为什么这么说，下面来说几个很常见的场景。</p>

<h2 id="repl-的核心思想">REPL 的核心思想</h2>

<p>如果你是 iOSer，你一定还会记得当年 Swift 刚刚诞生的时候，有一个主打的功能就是 <strong>REPL 交互式开发环境</strong>。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1601284781928-6b274959-8352-4ad8-a71b-c7f7e5f9cba9.png" alt="" /></p>

<p>当然，作为动态性十分强大的 Lisp 和 Ruby 也有对应的 REPL 工具。例如 Ruby 的 irb 和 pry 都是十分强大的 REPL。为什么这里要提及 REPL 呢？<strong>因为在这个名字中，E 就是 eval 的意思。</strong></p>

<p>REPL 对应的英文是 <strong>Read-Eval-Print Loop</strong>。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602156287860-47a6a0d4-e12b-40bd-8a02-7f18a56acf4e.png" alt="" /></p>

<ul>
  <li>Read 读入一个来自于用户的表达式，将其放入内存；</li>
  <li>Eval 求值函数，负责处理内部的数据结构并对上下文逻辑求值；</li>
  <li>Print 输出方法，将结果呈现给用户，完成交互。</li>
</ul>

<p>REPL 的模型让大家对于语言的学习和调试也有着增速作用，因为“Read - Eval - Print” 这种循环要比 “Code - Compile - Run - Debug” 这种循环更加敏捷。</p>

<p>在 Lisp 的思想中，为了实现一个 Lisp REPL ，只需要实现这三个函数和一个轮循的函数即可。当然这里我们忽略掉复杂的求值函数，因为它就是一个解释器。</p>

<p>有了这个思想，一个最简单的 REPL 就可以使用如下的形式表达：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c1"># Lisp 中</span>
<span class="p">(</span><span class="kp">loop</span> <span class="p">(</span><span class="nb">print</span> <span class="p">(</span><span class="nb">eval</span> <span class="p">(</span><span class="n">read</span><span class="p">))))</span>

<span class="c1"># Ruby 中</span>
<span class="k">while</span> <span class="p">[</span><span class="k">case</span><span class="p">]</span>
  <span class="nb">print</span><span class="p">(</span><span class="nb">eval</span><span class="p">(</span><span class="n">read</span><span class="p">))</span>
<span class="k">end</span>
</code></pre></div></div>

<h2 id="简单聊聊-hotpatch">简单聊聊 HotPatch</h2>

<p>大约在 2 年前，iOS 比较流行使用 JSPatch/RN 基于 JavaScriptCore 提供的 iOS 热修复和动态化方案。其核心的思路基本都是下发 JavaScript 脚本来调用 Objective-C，从而实现逻辑注入。</p>

<p>JSPatch 尤其被大家所知，需要编写大量的 JavaScript 代码来调用 Objective-C 方法，当然官方也看到了这一效率的洼地，并制作了 JSPatch 的语法转化器来间接优化这一过程。</p>

<p>但是无论如何优化，其实最大的根本问题是 Objective-C 这门语言不具备 Evaluation 的可 eval 特性，倘若拥有该特性，那其实就可以跨越使用 JavaScript 做桥接的诸多问题。</p>

<p>我们都知道 Objective-C 的 Runtime 利用消息转发可以动态执行任何 Objective-C 方法，这也就给了我们一个启示。假如我们<strong>自制一个轻量级解释器，动态解释 Objective-C 代码，利用 Runtime 消息转发来动态执行 Objective-C 方法，就可以实现一个“准 eval 方法”</strong>。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602158120322-b10b302a-4bde-4a4e-8324-4f5830e7c2fc.png" alt="" /></p>

<p>这种思路在 GitHub 上也已经有朋友开源出了 Demo - <a href="https://github.com/lilidan/OCEval">OCEval</a>。不同于 Clang 的编译过程，他进行了精简：</p>

<ol>
  <li>去除了 Preprocesser 的预编译环节，保留了 Lexer 词法分析和 Parser 语法分析，</li>
  <li>利用 <code class="language-plaintext highlighter-rouge">NSMethodSignature</code> 封装方法，结合递归下降，使用 Runtime 对方法进行消息转发。</li>
</ol>

<p>利用这种思路的还有另外一个 <a href="https://github.com/SilverFruity/OCRunner">OCRunner</a> 项目。</p>

<p>这些都是通过自制解释器，实现 eval 特性，进而配合 libffi 来实现。</p>

<h2 id="ruby-中的-eval-和-binding">Ruby 中的 <code class="language-plaintext highlighter-rouge">eval</code> 和 <code class="language-plaintext highlighter-rouge">binding</code></h2>

<p><strong>Ruby 中的 eval 方法其实很好理解，就是将 Ruby 代码以字符串的形式作为参数传入，然后进行执行。</strong></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">str</span> <span class="o">=</span> <span class="s1">'Hello'</span>
<span class="nb">puts</span> <span class="nb">eval</span><span class="p">(</span><span class="s2">"str + ' CocoaPods'"</span><span class="p">)</span> <span class="c1"># Hello CocoaPods</span>
</code></pre></div></div>

<p>上面就是一个例子，我们发现传入的代码 <code class="language-plaintext highlighter-rouge">str + ' CocoaPods'</code>  在 <code class="language-plaintext highlighter-rouge">eval</code> 方法中已经变成 Ruby 代码执行，并返回结果 <code class="language-plaintext highlighter-rouge">'Hello CocoaPods'</code>  字符串。</p>

<p>在<a href="/2020/09/16/cocoapods-story-4.html">「Podfile 的解析逻辑」</a>中讲到， CocoaPods 中也使用了 <code class="language-plaintext highlighter-rouge">eval</code> 方法，从而以 Ruby 脚本的形式，执行了 <code class="language-plaintext highlighter-rouge">Podfile</code> 文件中的逻辑。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_ruby</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">contents</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
  <span class="c1"># ... </span>
  <span class="n">podfile</span> <span class="o">=</span> <span class="no">Podfile</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="k">do</span>
    <span class="k">begin</span>
      <span class="c1"># 执行 Podfile 中的逻辑</span>
      <span class="nb">eval</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="kp">nil</span><span class="p">,</span> <span class="n">path</span><span class="p">.</span><span class="nf">to_s</span><span class="p">)</span>
    <span class="k">rescue</span> <span class="no">Exception</span> <span class="o">=&gt;</span> <span class="n">e</span>
      <span class="n">message</span> <span class="o">=</span> <span class="s2">"Invalid `</span><span class="si">#{</span><span class="n">path</span><span class="p">.</span><span class="nf">basename</span><span class="si">}</span><span class="s2">` file: </span><span class="si">#{</span><span class="n">e</span><span class="p">.</span><span class="nf">message</span><span class="si">}</span><span class="s2">"</span>
      <span class="k">raise</span> <span class="no">DSLError</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">contents</span><span class="p">)</span>
    <span class="k">end</span>
  <span class="k">end</span>
  <span class="n">podfile</span>
<span class="k">end</span>
</code></pre></div></div>

<p>当然，在 CocoaPods 中仅仅是用了 <code class="language-plaintext highlighter-rouge">eval</code> 方法的第一层，对于我们学习者来说肯定不能满足于此。</p>

<p>在 Ruby 中， <code class="language-plaintext highlighter-rouge">Kernel</code> 有一个方法 <code class="language-plaintext highlighter-rouge">binding</code> ，它会返回一个 Binding 类型的对象。这个 Binding 对象就是我们俗称的<strong>绑定</strong>，它封装了当前执行上下文的所有绑定，包括变量、方法、Block 和 <code class="language-plaintext highlighter-rouge">self</code> 的名称绑定等，这些绑定直接决定了面向对象语言中的执行环境。</p>

<p>那么这个 Binding 对象在 <code class="language-plaintext highlighter-rouge">eval</code> 方法中怎么使用呢？其实就是 <code class="language-plaintext highlighter-rouge">eval</code> 方法的第二个参数。这个在 CocoaPods 中运行 Podfile 代码中并没有使用到。我们下面来做一个例子：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">foo</span> 
  <span class="nb">name</span> <span class="o">=</span> <span class="s1">'Gua'</span>
  <span class="nb">binding</span>
<span class="k">end</span>

<span class="nb">eval</span><span class="p">(</span><span class="s1">'p name'</span><span class="p">,</span> <span class="n">foo</span><span class="p">)</span> <span class="c1"># Gua</span>
</code></pre></div></div>

<p>在这个例子中，我们的 <code class="language-plaintext highlighter-rouge">foo</code> 方法就是我们上面说的执行环境，在这个环境里定义了 <code class="language-plaintext highlighter-rouge">name</code> 这个变量，并在方法体最后返回 <code class="language-plaintext highlighter-rouge">binding</code> 方法调用结果。在下面使用 <code class="language-plaintext highlighter-rouge">eval</code> 方法的时候，当作 <code class="language-plaintext highlighter-rouge">Kernel#binding</code> 入参传入，便可以成功输出 <code class="language-plaintext highlighter-rouge">name</code> 变量。</p>

<h2 id="toplevel_binding-全局常量"><code class="language-plaintext highlighter-rouge">TOPLEVEL_BINDING</code> 全局常量</h2>

<p>在 Ruby 中 <code class="language-plaintext highlighter-rouge">main</code> 对象是最顶级范围，Ruby 中的任何对象都至少需要在次作用域范围内被实例化。为了随时随地地访问 <code class="language-plaintext highlighter-rouge">main</code> 对象的上下文，Ruby 提供了一个名为 <code class="language-plaintext highlighter-rouge">TOPLEVEL_BINDING</code> 的全局常量，<strong>它指向一个封装了顶级绑定的对象</strong>。
便于理解，举个例子：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="vi">@a</span> <span class="o">=</span> <span class="s2">"Hello"</span>

<span class="k">class</span> <span class="nc">Addition</span>
  <span class="k">def</span> <span class="nf">add</span>
    <span class="no">TOPLEVEL_BINDING</span><span class="p">.</span><span class="nf">eval</span><span class="p">(</span><span class="s2">"@a += ' Gua'"</span><span class="p">)</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="no">Addition</span><span class="p">.</span><span class="nf">new</span><span class="p">.</span><span class="nf">add</span>

<span class="nb">p</span> <span class="no">TOPLEVEL_BINDING</span><span class="p">.</span><span class="nf">receiver</span> <span class="c1"># main</span>
<span class="nb">p</span> <span class="vi">@a</span> <span class="c1"># Hello Gua</span>
</code></pre></div></div>

<p>这段代码中，<code class="language-plaintext highlighter-rouge">Binding#receiver</code> 方法返回 <code class="language-plaintext highlighter-rouge">Kernel#binding</code> 消息的接收者。为此，则保存了调用执行上下文 - 在我们的示例中，是 <code class="language-plaintext highlighter-rouge">main</code> 对象。</p>

<p>然后我们在 Addition 类的实例中使用 <code class="language-plaintext highlighter-rouge">TOPLEVEL_BINDING</code> 全局常量访问全局的 <code class="language-plaintext highlighter-rouge">@a</code> 变量。</p>

<h2 id="总说-ruby-eval-特性">总说 Ruby Eval 特性</h2>

<p>以上的简单介绍如果你曾经阅读过 SICP（Structture and Interpretation of Computer Programs）这一神书的第四章后，一定会有更加深刻的理解。</p>

<p><strong>我们将所有的语句当作求值，用语言去描述过程，用与被求值的语言相同的语言写出的求值器被称作元循环；eval 在元循环中，参数是一个表达式和一个环境，这也与 Ruby 的 <code class="language-plaintext highlighter-rouge">eval</code> 方法完全吻合。</strong></p>

<p>不得不说，Ruby 的很多思想，站在 SICP 的肩膀上。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602158921983-a4538257-84e2-48e8-bd24-6d6d3bbc9eb0.png" alt="" /></p>

<h1 id="类似于-method-swizzling-的-alias">类似于 Method Swizzling 的 <code class="language-plaintext highlighter-rouge">alias</code></h1>

<p>对于广大 iOSer 一定都十分了解被称作 Runtime 黑魔法的 Method Swizzling。这其实是动态语言大都具有都特性。</p>

<p>在 iOS 中，使用 Selector 和 Implementation（即 IMP）的指向交换，从而实现了方法的替换。这种替换是发生在运行时的。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602159208203-64baa017-a1e9-4383-9b78-d79f675bce67.png" alt="" /></p>

<p>在 Ruby 中，也有类似的方法。为了全面的了解 Ruby 中的 “Method Swizzling”，我们需要了解这几个关于元编程思想的概念：<strong>Open Class 特性与环绕别名。</strong>这两个特性也是实现 CocoaPods 插件化的核心依赖。</p>

<h2 id="open-class-与特异方法">Open Class 与特异方法</h2>

<p>Open Class 特性就是在一个类已经完成定义之后，再次向其中添加方法。在 Ruby 中的实现方法就是<strong>定义同名类</strong>。</p>

<p>在 Ruby 中不会像 Objective-C 和 Swift 一样被认为是编译错误，后者需要使用 Category 和 Extension 特殊的关键字语法来约定是扩展。<strong>而是把同名类中的定义方法全部附加到已定义的旧类中，不重名的增加，重名的覆盖</strong>。以下为示例代码：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">def</span> <span class="nf">m1</span>
    <span class="nb">puts</span> <span class="s2">"m1"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">def</span> <span class="nf">m2</span> 
    <span class="nb">puts</span> <span class="s2">"m2"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="no">Foo</span><span class="p">.</span><span class="nf">new</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1</span>
<span class="no">Foo</span><span class="p">.</span><span class="nf">new</span><span class="p">.</span><span class="nf">m2</span> <span class="c1"># m2</span>

<span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">def</span> <span class="nf">m1</span>
    <span class="nb">puts</span> <span class="s2">"m1 new"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="no">Foo</span><span class="p">.</span><span class="nf">new</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1 new</span>
<span class="no">Foo</span><span class="p">.</span><span class="nf">new</span><span class="p">.</span><span class="nf">m2</span> <span class="c1"># m2</span>
</code></pre></div></div>

<p><strong>特异方法</strong>和 Open Class 有点类似，不过<strong>附加的方法不是附加到类中，而是附加到特定到实例中</strong>。被附加到方法仅仅在目标实例中存在，不会影响该类到其他实例。示例代码：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">def</span> <span class="nf">m1</span>
    <span class="nb">puts</span> <span class="s2">"m1"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="n">foo1</span> <span class="o">=</span> <span class="no">Foo</span><span class="p">.</span><span class="nf">new</span>

<span class="k">def</span> <span class="nc">foo1</span><span class="o">.</span><span class="nf">m2</span><span class="p">()</span>
  <span class="nb">puts</span> <span class="s2">"m2"</span>
<span class="k">end</span>

<span class="n">foo1</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1</span>
<span class="n">foo1</span><span class="p">.</span><span class="nf">m2</span> <span class="c1"># m2</span>

<span class="n">foo2</span> <span class="o">=</span> <span class="no">Foo</span><span class="p">.</span><span class="nf">new</span>
<span class="n">foo2</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1</span>
<span class="c1"># foo2.m2 undefined method `m2' for #&lt;Foo:0x00007f88bb08e238&gt; (NoMethodError)</span>
</code></pre></div></div>

<h2 id="环绕别名around-aliases">环绕别名（Around Aliases）</h2>

<p>其实环绕别名只是一种特殊的写法，这里使用了 Ruby 的 <code class="language-plaintext highlighter-rouge">alias</code> 关键字以及上文提到的 Open Class 的特性。</p>

<p>首先先介绍一下 Ruby 的 <code class="language-plaintext highlighter-rouge">alias</code> 关键字，其实很简单，<strong>就是给一个方法起一个别名</strong>。但是 <code class="language-plaintext highlighter-rouge">alias</code> 配合上之前的 Open Class 特性，就可以达到我们所说的 Method Swizzling 效果。</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">def</span> <span class="nf">m1</span>
    <span class="nb">puts</span> <span class="s2">"m1"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="n">foo</span> <span class="o">=</span> <span class="no">Foo</span><span class="p">.</span><span class="nf">new</span>
<span class="n">foo</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1</span>

<span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">alias</span> <span class="ss">:origin_m1</span> <span class="ss">:m1</span>
  <span class="k">def</span> <span class="nf">m1</span>
    <span class="n">origin_m1</span>
    <span class="nb">puts</span> <span class="s2">"Hook it!"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="n">foo</span><span class="p">.</span><span class="nf">m1</span> 
<span class="c1"># m1</span>
<span class="c1"># Hook it!</span>
</code></pre></div></div>

<p>虽然在第一个位置已经定义了 <code class="language-plaintext highlighter-rouge">Foo#m1</code>  方法，但是由于 Open Class 的重写机制以及 <code class="language-plaintext highlighter-rouge">alias</code> 的别名设置，我们将 <code class="language-plaintext highlighter-rouge">m1</code> 已经修改成了新的方法，旧的 <code class="language-plaintext highlighter-rouge">m1</code> 方法使用 <code class="language-plaintext highlighter-rouge">origin_m1</code> 也可以调用到。如此也就完成了类似于 Objective-C 中的 Method Swizzling 机制。</p>

<p>总结一下环绕别名，其实就是<strong>给方法定义一个别名，然后重新定义这个方法，在新的方法中使用别名调用老方法</strong>。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1602159579722-ad6461a6-31cd-407e-b718-089e9398cee3.png" alt="" /></p>

<h2 id="猴子补丁monkey-patch">猴子补丁（Monkey Patch）</h2>

<p>既然说到了 <code class="language-plaintext highlighter-rouge">alias</code> 别名，那么就顺便说一下<strong>猴子补丁</strong>这个特性。猴子补丁<strong>区别于环绕别名的方式，它主要目的是在运行时动态替换并可以暂时性避免程序崩溃</strong>。</p>

<p>先聊聊背景，由于 Open Class 和环绕别名这两个特性，Ruby 在运行时改变属性已经十分容易了。但是如果我们现在有一个需求，就是 **需要动态的进行 Patch ** ，而不是只要 <code class="language-plaintext highlighter-rouge">alias</code> 就全局替换，这要怎么做呢？</p>

<p>这里我们引入 Ruby 中的另外两个关键字 <code class="language-plaintext highlighter-rouge">refine</code> 和 <code class="language-plaintext highlighter-rouge">using</code> ，通过它们我们可以动态实现 Patch。举个例子：</p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">class</span> <span class="nc">Foo</span>
  <span class="k">def</span> <span class="nf">m1</span>
    <span class="nb">puts</span> <span class="s2">"m1"</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="n">foo</span> <span class="o">=</span> <span class="no">Foo</span><span class="p">.</span><span class="nf">new</span>
<span class="n">foo</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1</span>

<span class="s2">"""
定义一个 Patch
"""</span>

<span class="k">module</span> <span class="nn">TemproaryPatch</span>
  <span class="n">refine</span> <span class="no">Foo</span> <span class="k">do</span> 
    <span class="k">def</span> <span class="nf">m1</span> 
      <span class="nb">puts</span> <span class="s2">"m1 bugfix"</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>

<span class="n">using</span> <span class="no">TemproaryPatch</span>

<span class="n">foo2</span> <span class="o">=</span> <span class="no">Foo</span><span class="p">.</span><span class="nf">new</span>
<span class="n">foo2</span><span class="p">.</span><span class="nf">m1</span> <span class="c1"># m1 bugfix</span>
</code></pre></div></div>

<p>上面代码中，我们先使用了 <code class="language-plaintext highlighter-rouge">refine</code> 方法重新定义了 <code class="language-plaintext highlighter-rouge">m1</code> 方法，定义完之后它并不会立即生效，而是在我们使用 <code class="language-plaintext highlighter-rouge">using TemporaryPatch</code> 时，才会生效。这样也就实现了动态 Patch 的需求。</p>

<h2 id="总说-alias-特性">总说 alias 特性</h2>

<p>Ruby 的 <code class="language-plaintext highlighter-rouge">alias</code> 使用实在时太灵活了，这也导致了为什么 Ruby 很容易的就可以实现插件化能力。因为所有的方法都可以通过环绕别名的方式进行 Hook ，从而实现自己的 Gem 插件。</p>

<p>除了以上介绍的一些扩展方式，其实 Ruby 还有更多修改方案。例如 <code class="language-plaintext highlighter-rouge">alias_method</code> 、 <code class="language-plaintext highlighter-rouge">extend</code> 、 <code class="language-plaintext highlighter-rouge">refinement</code> 等。如果后面 CocoaPods 有所涉及，我们也会跟进介绍一些。</p>

<h1 id="总结">总结</h1>

<p>本文通过 CocoaPods 中的两个使用到的特性 Eval 和 Alias，讲述了很多 Ruby 当中有意思的语法特性和元编程思想。Ruby 在众多的语言中，因为注重思想和语法优雅脱颖而出，也让我个人对语言有很大的思想提升。</p>

<p>如果你有经历，我也强烈推荐你阅读 SICP 和「Ruby 元编程」这两本书，相信它们也会让你在语言设计的理解上，有着更深的认识。从共性提炼到方法论，从语言升华到经验。</p>

<h1 id="知识点问题梳理">知识点问题梳理</h1>

<p>这里罗列了四个问题用来考察你是否已经掌握了这篇文章，你可以在评论区及时回答问题与作者交流。如果没有建议你加入<strong>收藏</strong>再次阅读：</p>

<ol>
  <li>REPL 的核心思想是什么？与 Evaluation 特性有什么关系？</li>
  <li>Ruby 中 <code class="language-plaintext highlighter-rouge">eval</code> 方法作用是什么？Binding 对象用来干什么？</li>
  <li>Ruby 是否可以实现 Method Swizzling 这种功能？</li>
  <li>Open Class 是什么？环绕别名如何利用？</li>
</ol>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="CocoaPods 历险记" /><category term="Ruby in CocoaPods" /><category term="Ruby" /><summary type="html"><![CDATA[CocoaPods 是使用 Ruby 这门脚本语言实现的工具。Ruby 有很多优质的特性被 CocoaPods 所利用，为了在后续的源码阅读中不会被这些用法阻塞，所以在这个系列中，会给出一些 CocoaPods 的番外篇，来介绍 Ruby 及其当中的一些语言思想。 今天这一篇我们来聊聊 Ruby 中的一些十分“动态”的特性：eval 特性和 alias 特性。 说说 Eval 特性 源自 Lisp 的 Evaluation 在一些语言中，eval 方法是将一个字符串当作表达式执行而返回一个结果的方法；在另外一些中，eval 它所传入的不一定是字符串，还有可能是抽象句法形势，Lisp 就是这种语言，并且 Lisp 也是首先提出使用 eval 方法的语言，并提出了 Evaluation 这个特性。这也使得 Lisp 这门语言可以实现脱离编译这套体系而动态执行的结果。 Lisp 中的 eval 方法预期是：将表达式作为参数传入到 eval 方法，并声明给定形式的返回值，运行时动态计算。 下面是一个 Lisp Evaluation 代码的例子（ Scheme 方言 RRS 及以后版本）： ; 将 f1 设置为表达式 (+ 1 2 3) (define f1 '(+ 1 2 3)) ; 执行 f1 (+ 1 2 3) 这个表达式，并返回 6 (eval f1 user-initial-environment) 可能你会觉得：这只是一个简单的特性，为什么会称作黑魔法特性？ 因为 Evaluation 这种可 eval 特性是很多思想、落地工具的基础。为什么这么说，下面来说几个很常见的场景。 REPL 的核心思想 如果你是 iOSer，你一定还会记得当年 Swift 刚刚诞生的时候，有一个主打的功能就是 REPL 交互式开发环境。 当然，作为动态性十分强大的 Lisp 和 Ruby 也有对应的 REPL 工具。例如 Ruby 的 irb 和 pry 都是十分强大的 REPL。为什么这里要提及 REPL 呢？因为在这个名字中，E 就是 eval 的意思。 REPL 对应的英文是 Read-Eval-Print Loop。 Read 读入一个来自于用户的表达式，将其放入内存； Eval 求值函数，负责处理内部的数据结构并对上下文逻辑求值； Print 输出方法，将结果呈现给用户，完成交互。 REPL 的模型让大家对于语言的学习和调试也有着增速作用，因为“Read - Eval - Print” 这种循环要比 “Code - Compile - Run - Debug” 这种循环更加敏捷。 在 Lisp 的思想中，为了实现一个 Lisp REPL ，只需要实现这三个函数和一个轮循的函数即可。当然这里我们忽略掉复杂的求值函数，因为它就是一个解释器。 有了这个思想，一个最简单的 REPL 就可以使用如下的形式表达： # Lisp 中 (loop (print (eval (read)))) # Ruby 中 while [case] print(eval(read)) end 简单聊聊 HotPatch 大约在 2 年前，iOS 比较流行使用 JSPatch/RN 基于 JavaScriptCore 提供的 iOS 热修复和动态化方案。其核心的思路基本都是下发 JavaScript 脚本来调用 Objective-C，从而实现逻辑注入。 JSPatch 尤其被大家所知，需要编写大量的 JavaScript 代码来调用 Objective-C 方法，当然官方也看到了这一效率的洼地，并制作了 JSPatch 的语法转化器来间接优化这一过程。 但是无论如何优化，其实最大的根本问题是 Objective-C 这门语言不具备 Evaluation 的可 eval 特性，倘若拥有该特性，那其实就可以跨越使用 JavaScript 做桥接的诸多问题。 我们都知道 Objective-C 的 Runtime 利用消息转发可以动态执行任何 Objective-C 方法，这也就给了我们一个启示。假如我们自制一个轻量级解释器，动态解释 Objective-C 代码，利用 Runtime 消息转发来动态执行 Objective-C 方法，就可以实现一个“准 eval 方法”。 这种思路在 GitHub 上也已经有朋友开源出了 Demo - OCEval。不同于 Clang 的编译过程，他进行了精简： 去除了 Preprocesser 的预编译环节，保留了 Lexer 词法分析和 Parser 语法分析， 利用 NSMethodSignature 封装方法，结合递归下降，使用 Runtime 对方法进行消息转发。 利用这种思路的还有另外一个 OCRunner 项目。 这些都是通过自制解释器，实现 eval 特性，进而配合 libffi 来实现。 Ruby 中的 eval 和 binding Ruby 中的 eval 方法其实很好理解，就是将 Ruby 代码以字符串的形式作为参数传入，然后进行执行。 str = 'Hello' puts eval("str + ' CocoaPods'") # Hello CocoaPods 上面就是一个例子，我们发现传入的代码 str + ' CocoaPods'  在 eval 方法中已经变成 Ruby 代码执行，并返回结果 'Hello CocoaPods'  字符串。 在「Podfile 的解析逻辑」中讲到， CocoaPods 中也使用了 eval 方法，从而以 Ruby 脚本的形式，执行了 Podfile 文件中的逻辑。 def self.from_ruby(path, contents = nil) # ... podfile = Podfile.new(path) do begin # 执行 Podfile 中的逻辑 eval(contents, nil, path.to_s) rescue Exception =&gt; e message = "Invalid `#{path.basename}` file: #{e.message}" raise DSLError.new(message, path, e, contents) end end podfile end 当然，在 CocoaPods 中仅仅是用了 eval 方法的第一层，对于我们学习者来说肯定不能满足于此。 在 Ruby 中， Kernel 有一个方法 binding ，它会返回一个 Binding 类型的对象。这个 Binding 对象就是我们俗称的绑定，它封装了当前执行上下文的所有绑定，包括变量、方法、Block 和 self 的名称绑定等，这些绑定直接决定了面向对象语言中的执行环境。 那么这个 Binding 对象在 eval 方法中怎么使用呢？其实就是 eval 方法的第二个参数。这个在 CocoaPods 中运行 Podfile 代码中并没有使用到。我们下面来做一个例子： def foo name = 'Gua' binding end eval('p name', foo) # Gua 在这个例子中，我们的 foo 方法就是我们上面说的执行环境，在这个环境里定义了 name 这个变量，并在方法体最后返回 binding 方法调用结果。在下面使用 eval 方法的时候，当作 Kernel#binding 入参传入，便可以成功输出 name 变量。 TOPLEVEL_BINDING 全局常量 在 Ruby 中 main 对象是最顶级范围，Ruby 中的任何对象都至少需要在次作用域范围内被实例化。为了随时随地地访问 main 对象的上下文，Ruby 提供了一个名为 TOPLEVEL_BINDING 的全局常量，它指向一个封装了顶级绑定的对象。 便于理解，举个例子： @a = "Hello" class Addition def add TOPLEVEL_BINDING.eval("@a += ' Gua'") end end Addition.new.add p TOPLEVEL_BINDING.receiver # main p @a # Hello Gua 这段代码中，Binding#receiver 方法返回 Kernel#binding 消息的接收者。为此，则保存了调用执行上下文 - 在我们的示例中，是 main 对象。 然后我们在 Addition 类的实例中使用 TOPLEVEL_BINDING 全局常量访问全局的 @a 变量。 总说 Ruby Eval 特性 以上的简单介绍如果你曾经阅读过 SICP（Structture and Interpretation of Computer Programs）这一神书的第四章后，一定会有更加深刻的理解。 我们将所有的语句当作求值，用语言去描述过程，用与被求值的语言相同的语言写出的求值器被称作元循环；eval 在元循环中，参数是一个表达式和一个环境，这也与 Ruby 的 eval 方法完全吻合。 不得不说，Ruby 的很多思想，站在 SICP 的肩膀上。 类似于 Method Swizzling 的 alias 对于广大 iOSer 一定都十分了解被称作 Runtime 黑魔法的 Method Swizzling。这其实是动态语言大都具有都特性。 在 iOS 中，使用 Selector 和 Implementation（即 IMP）的指向交换，从而实现了方法的替换。这种替换是发生在运行时的。 在 Ruby 中，也有类似的方法。为了全面的了解 Ruby 中的 “Method Swizzling”，我们需要了解这几个关于元编程思想的概念：Open Class 特性与环绕别名。这两个特性也是实现 CocoaPods 插件化的核心依赖。 Open Class 与特异方法 Open Class 特性就是在一个类已经完成定义之后，再次向其中添加方法。在 Ruby 中的实现方法就是定义同名类。 在 Ruby 中不会像 Objective-C 和 Swift 一样被认为是编译错误，后者需要使用 Category 和 Extension 特殊的关键字语法来约定是扩展。而是把同名类中的定义方法全部附加到已定义的旧类中，不重名的增加，重名的覆盖。以下为示例代码： class Foo def m1 puts "m1" end end class Foo def m2 puts "m2" end end Foo.new.m1 # m1 Foo.new.m2 # m2 class Foo def m1 puts "m1 new" end end Foo.new.m1 # m1 new Foo.new.m2 # m2 特异方法和 Open Class 有点类似，不过附加的方法不是附加到类中，而是附加到特定到实例中。被附加到方法仅仅在目标实例中存在，不会影响该类到其他实例。示例代码： class Foo def m1 puts "m1" end end foo1 = Foo.new def foo1.m2() puts "m2" end foo1.m1 # m1 foo1.m2 # m2 foo2 = Foo.new foo2.m1 # m1 # foo2.m2 undefined method `m2' for #&lt;Foo:0x00007f88bb08e238&gt; (NoMethodError) 环绕别名（Around Aliases） 其实环绕别名只是一种特殊的写法，这里使用了 Ruby 的 alias 关键字以及上文提到的 Open Class 的特性。 首先先介绍一下 Ruby 的 alias 关键字，其实很简单，就是给一个方法起一个别名。但是 alias 配合上之前的 Open Class 特性，就可以达到我们所说的 Method Swizzling 效果。 class Foo def m1 puts "m1" end end foo = Foo.new foo.m1 # m1 class Foo alias :origin_m1 :m1 def m1 origin_m1 puts "Hook it!" end end foo.m1 # m1 # Hook it! 虽然在第一个位置已经定义了 Foo#m1  方法，但是由于 Open Class 的重写机制以及 alias 的别名设置，我们将 m1 已经修改成了新的方法，旧的 m1 方法使用 origin_m1 也可以调用到。如此也就完成了类似于 Objective-C 中的 Method Swizzling 机制。 总结一下环绕别名，其实就是给方法定义一个别名，然后重新定义这个方法，在新的方法中使用别名调用老方法。 猴子补丁（Monkey Patch） 既然说到了 alias 别名，那么就顺便说一下猴子补丁这个特性。猴子补丁区别于环绕别名的方式，它主要目的是在运行时动态替换并可以暂时性避免程序崩溃。 先聊聊背景，由于 Open Class 和环绕别名这两个特性，Ruby 在运行时改变属性已经十分容易了。但是如果我们现在有一个需求，就是 **需要动态的进行 Patch ** ，而不是只要 alias 就全局替换，这要怎么做呢？ 这里我们引入 Ruby 中的另外两个关键字 refine 和 using ，通过它们我们可以动态实现 Patch。举个例子： class Foo def m1 puts "m1" end end foo = Foo.new foo.m1 # m1 """ 定义一个 Patch """ module TemproaryPatch refine Foo do def m1 puts "m1 bugfix" end end end using TemproaryPatch foo2 = Foo.new foo2.m1 # m1 bugfix 上面代码中，我们先使用了 refine 方法重新定义了 m1 方法，定义完之后它并不会立即生效，而是在我们使用 using TemporaryPatch 时，才会生效。这样也就实现了动态 Patch 的需求。 总说 alias 特性 Ruby 的 alias 使用实在时太灵活了，这也导致了为什么 Ruby 很容易的就可以实现插件化能力。因为所有的方法都可以通过环绕别名的方式进行 Hook ，从而实现自己的 Gem 插件。 除了以上介绍的一些扩展方式，其实 Ruby 还有更多修改方案。例如 alias_method 、 extend 、 refinement 等。如果后面 CocoaPods 有所涉及，我们也会跟进介绍一些。 总结 本文通过 CocoaPods 中的两个使用到的特性 Eval 和 Alias，讲述了很多 Ruby 当中有意思的语法特性和元编程思想。Ruby 在众多的语言中，因为注重思想和语法优雅脱颖而出，也让我个人对语言有很大的思想提升。 如果你有经历，我也强烈推荐你阅读 SICP 和「Ruby 元编程」这两本书，相信它们也会让你在语言设计的理解上，有着更深的认识。从共性提炼到方法论，从语言升华到经验。 知识点问题梳理 这里罗列了四个问题用来考察你是否已经掌握了这篇文章，你可以在评论区及时回答问题与作者交流。如果没有建议你加入收藏再次阅读： REPL 的核心思想是什么？与 Evaluation 特性有什么关系？ Ruby 中 eval 方法作用是什么？Binding 对象用来干什么？ Ruby 是否可以实现 Method Swizzling 这种功能？ Open Class 是什么？环绕别名如何利用？]]></summary></entry><entry><title type="html">二手房增值税分析 - 首付与差额</title><link href="https://www.desgard.com/2020/09/23/buy-big-house-in-sh-2.html" rel="alternate" type="text/html" title="二手房增值税分析 - 首付与差额" /><published>2020-09-23T00:00:00-08:00</published><updated>2020-09-23T00:00:00-08:00</updated><id>https://www.desgard.com/2020/09/23/buy-big-house-in-sh-2</id><content type="html" xml:base="https://www.desgard.com/2020/09/23/buy-big-house-in-sh-2.html"><![CDATA[<blockquote>
  <p>我给自己定了一个将近 700 天的计划，这就是在上海买房定居。于是开启了研究购房政策、研究小区和板块、研究购房注意事项等一系列的调研和研究。我将这些笔记归档成文章，发表在公众号与大家分享。</p>
</blockquote>

<p><strong>今天距离购房还有 665 天。</strong></p>

<p>虽然说二手房的价格便宜，但其实除了购房款以外，还有大大小小的多个税款。当我们累加上这些价格后才是最终的支出价格。</p>

<p>这篇笔记<strong>仅适用于上海 2020 年购入二手房的相关政策，其他省份和城市都略有区别</strong>。</p>

<p><strong>二手房交易中，这篇我们只关注增值税。</strong></p>

<p>首先，我们先要了解几个概念。</p>

<h1 id="普通住宅认定标准">普通住宅认定标准</h1>

<p><strong>什么是普通住宅？</strong></p>

<p>影响上海普通住宅认定标准的三个因素，一是<strong>总价</strong>，二是<strong>面积，</strong>三是<strong>圈层</strong>。</p>

<p>首先，满足以下任意一行条件的即为普通住宅，反之则为非普通住宅：</p>

<table>
  <thead>
    <tr>
      <th>圈层</th>
      <th>面积</th>
      <th>总价</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>内环内</td>
      <td>&lt; 140 平米</td>
      <td>≤ 450 万元</td>
    </tr>
    <tr>
      <td>内外环之间</td>
      <td>&lt; 140 平米</td>
      <td>≤ 310 万元</td>
    </tr>
    <tr>
      <td>外环外</td>
      <td>&lt; 140 平米</td>
      <td>≤ 230 万元</td>
    </tr>
  </tbody>
</table>

<p>知道了普通住宅的认定标准后有什么用呢？接下来就是关于普通和非普通的相关征税内容。</p>

<h1 id="增值税及其附加税">增值税及其附加税</h1>

<p>当所购房屋为<strong>普通住宅</strong>的时候，其增值税及其附加税按照下表为征收标准：</p>

<table>
  <thead>
    <tr>
      <th>年限</th>
      <th>征收标准</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>&lt; 2 年</td>
      <td>(税务核定价 ÷ 1.05) × (5% + 0.55%)</td>
    </tr>
    <tr>
      <td>[2, 5) 年</td>
      <td>免征</td>
    </tr>
    <tr>
      <td>≥ 5 年</td>
      <td>免征</td>
    </tr>
  </tbody>
</table>

<p>对应的，<strong>非普通住宅</strong>有以下的标准：</p>

<table>
  <thead>
    <tr>
      <th>年限</th>
      <th>征收标准</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>&lt; 2 年</td>
      <td>(税务核定价 ÷ 1.05) × (5% + 0.55%)</td>
    </tr>
    <tr>
      <td>[2, 5) 年</td>
      <td>((税务核定价- 买入价格) ÷ 1.05) × (5% + 0.55%)</td>
    </tr>
    <tr>
      <td>≥ 5 年</td>
      <td>((税务核定价 - 买入价格) ÷ 1.05) × (5% + 0.55%)</td>
    </tr>
  </tbody>
</table>

<p>这里的税务核定价是什么？又是如何确定的呢？</p>

<h2 id="税务核定价">税务核定价</h2>

<p>税务核定价，又被大家称之为<strong>二手房过户指导价</strong>。它是由当地税务部门确定的，核定价存在的意义主要是“兜底”，简单来说就是当买卖双方的网签价格低于核定价时，税务部门将不再根据<strong>网签价（也就是协商好的交易价格）</strong> 来确定税基，而是以核定价为标准来确定税基。</p>

<p>所以你应该明白了，核定价明显就是为了对付“阴阳合同”的。是的，它本质上是为了保证税收。</p>

<p>试想一下，如果买卖双方为了避税，网签价定为 1 元，那么这套房子就完全没有任何税费了。</p>

<p>那么税务核定价格一般是多少呢？</p>

<p>这个数据我在百度和谷歌也检索了很久，没有办法得到一组批量数据来做数据拟合。核定价格一般也不会对外公布，需要自己去税务机关咨询，也只能得到一个大概的数据。</p>

<p>因为在确定房屋的核定价时，要参考地段、面积等诸多因素，所以这个是很难作出表达式来加权表示的。</p>

<p><strong>由于税务核定价一般是用来“兜底”的，所以我们在这篇文章里做计算的时候，假设税务核定价是网签价格的 85% 来计算。</strong></p>

<h2 id="核定价影响贷款额度">核定价影响贷款额度</h2>

<p>虽然在「公积金贷买房能省多少钱」一文中，我们假定了任意房子的总价格 35% 首付，65% 贷款。</p>

<p>但是贷款额度参考的基数其实是<strong>税务核定价格</strong>，这也就意味着 <strong>往往购买二手房，你的首付是要多交一笔的，是大于 35% 的</strong> 。这是为什么？我们简单做一下计算：</p>

<p>假设我们想购买的二手房<strong>网签总价为 $T_{网签}$ 元</strong> ，且**假设税务核定价是网签价格的 85% **，此时税务核定价格 ：</p>

\[\begin{equation}
\left\{
\begin{array}{lr}
T_{贷款额度} = T_{核定} \times 65\% \notag \\
T_{核定} = T_{网签} \times 85\% \notag \\
\end{array} \\
\right.
\end{equation}\]

<p>带入后我们可以推导出：</p>

\[\begin{equation}
\left\{
\begin{array}{lr}
T_{贷款额度} = T_{网签} \times 55.25\%  \notag \\
T_{首付} = 1-55.25\% = 44.75\% \notag \\
\end{array} 
\right.
\end{equation}\]

<p>根据我们的假设条件，我们发现首付我们<strong>必须要凑够 44.75% 价格的首付，而贷款额度只有 55.25%</strong>。</p>

<p><strong>所以很多人都说，因为买了二手房，所以首付要高一些，将近 50%。其实就是上面这个原因。</strong></p>

<h1 id="增值税影响下的购房决策分析">增值税影响下的购房决策分析</h1>

<p>同样的，我们假设<strong>网签总价为 $T_{网签}$ 元</strong>，且 <strong>假设税务核定价是网签价格的 85%。</strong> 另外，我从知乎上检索到这么一组数据 「<a href="https://zhuanlan.zhihu.com/p/75780115" title="2015-2019 年上海各区房价涨跌情况">2015-2019 年上海各区房价涨跌情况</a>」。其中我需要用到各个区的二手房年化平均增长率，如下表总结：</p>

<table>
  <thead>
    <tr>
      <th>区域</th>
      <th>二手房价年化平均涨幅</th>
      <th>区域</th>
      <th>二手房价年化平均涨幅</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>长宁</td>
      <td>13.30%</td>
      <td>静安（包含老闸北）</td>
      <td>16.04%</td>
    </tr>
    <tr>
      <td>虹口</td>
      <td>15.79%</td>
      <td>闵行</td>
      <td>14.02%</td>
    </tr>
    <tr>
      <td>黄浦</td>
      <td>15.99%</td>
      <td>浦东（包含老南汇）</td>
      <td>12.55%</td>
    </tr>
    <tr>
      <td>普陀</td>
      <td>15.81%</td>
      <td>徐汇</td>
      <td>13.55%</td>
    </tr>
  </tbody>
</table>

<p>由上述数据我们可以计算出，上海二手房平均年化涨幅为 <strong>14.63%</strong>。有了涨幅数据之后，我们就可以求出差额的表达式，即 $T_{差额} = (税务核定价- 买入价格)$。当然，这里我们还要假设房屋年限为 $y$ 年</p>

\[\begin{align}
T_{差额} &amp;= T_{核定价} - T_{买入价格} \notag \\
\ &amp;= 0.85T_{网签} - T_{网签} \div (1 + 0.1463)^y \notag \\
\end{align}\]

<p>接下来我们来计算增值税的表达式：</p>

<p>当房屋是<strong>普通住宅</strong>时：</p>

\[\begin{equation}
T_{增值税} = \left\{
\begin{aligned}
&amp; \frac{T_{核定价}}{1.05} \times 5.55\% = 0.04497 · T_{网签} &amp;&amp; (y &lt; 2)\\
&amp; 0 &amp;&amp; (y \geq 2)
\end{aligned} \\
\right. \notag \\
\end{equation}\]

<p>当房屋是<strong>非普通住宅</strong>时：</p>

\[\begin{equation}
T_{增值税} = \left\{
\begin{aligned}
&amp; 0.04497 · T_{网签} &amp;&amp; (y &lt; 2) \notag \\ \\
&amp; (0.85T_{网签} - \frac{T_{网签}}{(1 + 0.1463)^y}) \times 0.0529 &amp;&amp; (y \geq 2) \notag \\ 
\end{aligned}
\right. \notag \\
\end{equation}\]

<p>我们可以看到，<strong>当年限小于 2 年的时候，无论是普通住宅还是非普通住宅，其增值税都要支付将近 4.5% 的增值税。且是否是普通住宅对增值税毫无影响。</strong></p>

<p>当年限大于等于 5 年的时候，普通住宅是免征增值税的，而非普通住宅是与年限和网签总价有一定关系的。我们来分析一下。</p>

<h2 id="非普通住宅的年限影响">非普通住宅的年限影响</h2>

<p>由于年份 $y$ 是离散的，所以我们将其投影在每一条折线上。以网签价格为横轴变量，来观察增值税与网签价的关系图：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardiav2-364823c4cf605b91cf8d8a57c6fe7844_1440w.jpg" alt="" /></p>

<p>我们可以得到以下结论：</p>

<ol>
  <li><strong>房龄越高，其所得税缴纳越多</strong>。这也是可以理解的，因为随着房价的上涨，其差额会逐渐变大。</li>
  <li><strong>所得税的增长幅度与年限呈现下降趋势</strong>。随着年限增高，增长差值逐渐降低。</li>
</ol>

<h2 id="增值税占比">增值税占比</h2>

<p>有没有什么方法来评估增值税最低的选择策略呢？我个人的想法是使用所占比例来考量。以下是我想的一个方法：</p>

\[P_{增值税所占比例} \approx \frac{T_{增值税}}{T_{网签价} + T_{增值税}}\]

<p>为什么这里是约等于呢？因为最后你需要支出的价格除了网签价格外，<strong>不仅只有增值税，还有其他的各种税款。</strong> 这里仅仅使用增值税来当作基数，可以放大增值税的比重，更能体现问题。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardiav2-2c8a663f4f74399c25d33fe351b292bc_1440w.jpg" alt="" /></p>

<p>作出图像我们可以发现，当我们购买“低龄”的房子，其所得税所占比例是更底的，<strong>5 年的二手房其所得税所占比例均值是 1.79%</strong>。</p>

<p>于是乎我们可以大致的计算出房龄与所得税所占比例的大致关系：</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1600825890934-a0417c8e-0029-4533-9068-d4a29a72e650.png" alt="" /></p>

<p>那么我们最好的策略是要选择最新的房子吗？其实并不是这样的，因为随着年限的增长，其单价也在逐渐升高。</p>

<p><strong>换句话说，当我总价固定后，随着房龄的降低，其面积是越来越小的。房屋面积是和我们的需求息息相关的。</strong></p>

<p>所以当我们做买房策略的时候，我们需要先确定<strong>需求面积</strong>和我们<strong>所支出的总价</strong>，然后尽可能的去购买新房就好了。</p>

<p>由于所得税在这里只能说明部分问题，具体的问题我将在后续的文中来具体分析。</p>

<h1 id="总结">总结</h1>

<ol>
  <li>购买二手房时，<strong>首付高一些，将近 50%。</strong> 其原因是因为税务核算价往往偏低，从而拉低了贷款比重，进而使得首付提高；</li>
  <li>当购买非普通住宅时，<strong>房龄越高，其所得税缴纳越多</strong>。因为随着房价的上涨，其差额会逐渐变大。</li>
  <li><strong>所得税的增长幅度与年限呈现下降趋势</strong>。随着年限增高，增长差值逐渐降低。</li>
  <li>确定<strong>需求面积</strong>和<strong>所支出的总价</strong>，尽可能的去购买新房。这与我们的正常认知也是相同的。</li>
</ol>

<h1 id="相关数据分析代码">相关数据分析代码</h1>

<p>以下代码由我个人编写，可在 Jupyter Notebook 环境下直接运行。</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="s">"""
网签价与增值税
"""</span>
<span class="c1"># encoding=utf-8
</span><span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="n">np</span>
<span class="kn">import</span> <span class="nn">math</span>
<span class="kn">from</span> <span class="nn">matplotlib</span> <span class="kn">import</span> <span class="n">pyplot</span>
<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="k">as</span> <span class="n">plt</span>
<span class="kn">from</span> <span class="nn">IPython.core.pylabtools</span> <span class="kn">import</span> <span class="n">figsize</span> <span class="c1"># import figsize
#figsize(12.5, 4) # 设置 figsize
</span><span class="n">plt</span><span class="p">.</span><span class="n">rcParams</span><span class="p">[</span><span class="s">'savefig.dpi'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">300</span> <span class="c1">#图片像素
</span><span class="n">plt</span><span class="p">.</span><span class="n">rcParams</span><span class="p">[</span><span class="s">'figure.dpi'</span><span class="p">]</span> <span class="o">=</span> <span class="mi">300</span> <span class="c1">#分辨率
</span>
<span class="c1"># 总价
</span><span class="n">ths</span> <span class="o">=</span> <span class="p">[</span><span class="n">i</span> <span class="o">*</span> <span class="mi">125000</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">1</span><span class="p">,</span> <span class="mi">100</span><span class="p">)]</span>

<span class="c1"># 年限
</span><span class="n">ys</span> <span class="o">=</span> <span class="p">[</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">21</span><span class="p">)]</span>

<span class="k">for</span> <span class="n">y</span> <span class="ow">in</span> <span class="n">ys</span><span class="p">:</span>
    <span class="c1"># 增值税计算
</span>    <span class="n">trs</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">th</span> <span class="ow">in</span> <span class="n">ths</span><span class="p">:</span>
        <span class="n">tr</span> <span class="o">=</span> <span class="p">(</span><span class="mf">0.85</span> <span class="o">*</span> <span class="n">th</span> <span class="o">-</span> <span class="n">th</span> <span class="o">/</span> <span class="p">((</span><span class="mi">1</span> <span class="o">+</span> <span class="mf">0.1463</span><span class="p">)</span> <span class="o">**</span> <span class="n">y</span><span class="p">))</span> <span class="o">*</span> <span class="mf">0.0529</span>
        <span class="n">trs</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">tr</span><span class="p">)</span>
        
    <span class="n">plt</span><span class="p">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ths</span><span class="p">,</span> <span class="n">trs</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="sa">f</span><span class="s">'</span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s">年'</span><span class="p">)</span>

<span class="n">plt</span><span class="p">.</span><span class="n">legend</span><span class="p">()</span>
<span class="n">plt</span><span class="p">.</span><span class="n">margins</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">subplots_adjust</span><span class="p">(</span><span class="n">bottom</span><span class="o">=</span><span class="mf">0.10</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">xlabel</span><span class="p">(</span><span class="s">'网签价/千万元'</span><span class="p">)</span> <span class="c1">#X轴标签
</span><span class="n">plt</span><span class="p">.</span><span class="n">ylabel</span><span class="p">(</span><span class="s">"增值税/元"</span><span class="p">)</span> <span class="c1">#Y轴标签
</span>

<span class="s">"""
网签价与增值税占比
"""</span>
<span class="c1"># 年限
</span><span class="n">ys</span> <span class="o">=</span> <span class="p">[</span><span class="n">i</span> <span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">,</span> <span class="mi">21</span><span class="p">)]</span>

<span class="k">for</span> <span class="n">y</span> <span class="ow">in</span> <span class="n">ys</span><span class="p">:</span>
    <span class="c1"># 增值税计算
</span>    <span class="n">trs</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">for</span> <span class="n">th</span> <span class="ow">in</span> <span class="n">ths</span><span class="p">:</span>
        <span class="n">tr</span> <span class="o">=</span> <span class="p">(</span><span class="mf">0.85</span> <span class="o">*</span> <span class="n">th</span> <span class="o">-</span> <span class="n">th</span> <span class="o">/</span> <span class="p">((</span><span class="mi">1</span> <span class="o">+</span> <span class="mf">0.1463</span><span class="p">)</span> <span class="o">**</span> <span class="n">y</span><span class="p">))</span> <span class="o">*</span> <span class="mf">0.0529</span>
        <span class="n">trs</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">tr</span> <span class="o">/</span> <span class="p">(</span><span class="n">th</span> <span class="o">+</span> <span class="n">tr</span><span class="p">))</span>
    <span class="k">print</span><span class="p">(</span><span class="nb">sum</span><span class="p">(</span><span class="n">trs</span><span class="p">)</span> <span class="o">/</span> <span class="nb">len</span><span class="p">(</span><span class="n">trs</span><span class="p">))</span>
    <span class="k">if</span> <span class="n">y</span> <span class="o">&gt;=</span> <span class="mi">10</span><span class="p">:</span>
        <span class="n">plt</span><span class="p">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ths</span><span class="p">,</span> <span class="n">trs</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="sa">f</span><span class="s">'</span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s">年'</span><span class="p">)</span>
    <span class="k">else</span><span class="p">:</span>
        <span class="n">plt</span><span class="p">.</span><span class="n">plot</span><span class="p">(</span><span class="n">ths</span><span class="p">,</span> <span class="n">trs</span><span class="p">,</span> <span class="n">marker</span><span class="o">=</span><span class="s">'*'</span><span class="p">,</span> <span class="n">label</span><span class="o">=</span><span class="sa">f</span><span class="s">'</span><span class="si">{</span><span class="n">y</span><span class="si">}</span><span class="s">年'</span><span class="p">)</span>

<span class="n">plt</span><span class="p">.</span><span class="n">legend</span><span class="p">()</span>
<span class="n">plt</span><span class="p">.</span><span class="n">margins</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">subplots_adjust</span><span class="p">(</span><span class="n">bottom</span><span class="o">=</span><span class="mf">0.10</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">xlabel</span><span class="p">(</span><span class="s">'网签价/千万元'</span><span class="p">)</span> <span class="c1">#X轴标签
</span><span class="n">plt</span><span class="p">.</span><span class="n">ylabel</span><span class="p">(</span><span class="s">"所得税占总支出比例"</span><span class="p">)</span> <span class="c1">#Y轴标签
</span>
<span class="s">"""
房龄与增值税占比
"""</span>
<span class="n">p</span> <span class="o">=</span> <span class="p">[</span>
    <span class="mf">0.017910502320842965</span><span class="p">,</span>
    <span class="mf">0.021189641628359904</span><span class="p">,</span>
    <span class="mf">0.024032438906425032</span><span class="p">,</span>
    <span class="mf">0.026498963556469416</span><span class="p">,</span>
    <span class="mf">0.028640531033586977</span><span class="p">,</span>
    <span class="mf">0.030501094013867885</span><span class="p">,</span>
    <span class="mf">0.032118385667131544</span><span class="p">,</span>
    <span class="mf">0.03352486519307519</span><span class="p">,</span>
    <span class="mf">0.034748504347376426</span><span class="p">,</span>
    <span class="mf">0.035813445129716175</span><span class="p">,</span>
    <span class="mf">0.03674055234381547</span><span class="p">,</span>
    <span class="mf">0.03754787981470654</span><span class="p">,</span>
    <span class="mf">0.038251065262737784</span><span class="p">,</span>
    <span class="mf">0.03886366589974932</span><span class="p">,</span>
    <span class="mf">0.03939744452077101</span><span class="p">,</span>
    <span class="mf">0.039862614060287876</span><span class="p">,</span>
<span class="p">]</span>

<span class="n">plt</span><span class="p">.</span><span class="n">plot</span><span class="p">(</span><span class="n">p</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">marker</span><span class="o">=</span><span class="s">'o'</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">legend</span><span class="p">()</span>
<span class="n">plt</span><span class="p">.</span><span class="n">margins</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">xlabel</span><span class="p">(</span><span class="s">'增值税占总支出比例'</span><span class="p">)</span> <span class="c1">#X轴标签
</span><span class="n">plt</span><span class="p">.</span><span class="n">ylabel</span><span class="p">(</span><span class="s">"房子年限/年"</span><span class="p">)</span> <span class="c1">#Y轴标签
</span></code></pre></div></div>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="冬瓜买房笔记" /><category term="数学建模" /><summary type="html"><![CDATA[我给自己定了一个将近 700 天的计划，这就是在上海买房定居。于是开启了研究购房政策、研究小区和板块、研究购房注意事项等一系列的调研和研究。我将这些笔记归档成文章，发表在公众号与大家分享。 今天距离购房还有 665 天。 虽然说二手房的价格便宜，但其实除了购房款以外，还有大大小小的多个税款。当我们累加上这些价格后才是最终的支出价格。 这篇笔记仅适用于上海 2020 年购入二手房的相关政策，其他省份和城市都略有区别。 二手房交易中，这篇我们只关注增值税。 首先，我们先要了解几个概念。 普通住宅认定标准 什么是普通住宅？ 影响上海普通住宅认定标准的三个因素，一是总价，二是面积，三是圈层。 首先，满足以下任意一行条件的即为普通住宅，反之则为非普通住宅： 圈层 面积 总价 内环内 &lt; 140 平米 ≤ 450 万元 内外环之间 &lt; 140 平米 ≤ 310 万元 外环外 &lt; 140 平米 ≤ 230 万元 知道了普通住宅的认定标准后有什么用呢？接下来就是关于普通和非普通的相关征税内容。 增值税及其附加税 当所购房屋为普通住宅的时候，其增值税及其附加税按照下表为征收标准： 年限 征收标准 &lt; 2 年 (税务核定价 ÷ 1.05) × (5% + 0.55%) [2, 5) 年 免征 ≥ 5 年 免征 对应的，非普通住宅有以下的标准： 年限 征收标准 &lt; 2 年 (税务核定价 ÷ 1.05) × (5% + 0.55%) [2, 5) 年 ((税务核定价- 买入价格) ÷ 1.05) × (5% + 0.55%) ≥ 5 年 ((税务核定价 - 买入价格) ÷ 1.05) × (5% + 0.55%) 这里的税务核定价是什么？又是如何确定的呢？ 税务核定价 税务核定价，又被大家称之为二手房过户指导价。它是由当地税务部门确定的，核定价存在的意义主要是“兜底”，简单来说就是当买卖双方的网签价格低于核定价时，税务部门将不再根据网签价（也就是协商好的交易价格） 来确定税基，而是以核定价为标准来确定税基。 所以你应该明白了，核定价明显就是为了对付“阴阳合同”的。是的，它本质上是为了保证税收。 试想一下，如果买卖双方为了避税，网签价定为 1 元，那么这套房子就完全没有任何税费了。 那么税务核定价格一般是多少呢？ 这个数据我在百度和谷歌也检索了很久，没有办法得到一组批量数据来做数据拟合。核定价格一般也不会对外公布，需要自己去税务机关咨询，也只能得到一个大概的数据。 因为在确定房屋的核定价时，要参考地段、面积等诸多因素，所以这个是很难作出表达式来加权表示的。 由于税务核定价一般是用来“兜底”的，所以我们在这篇文章里做计算的时候，假设税务核定价是网签价格的 85% 来计算。 核定价影响贷款额度 虽然在「公积金贷买房能省多少钱」一文中，我们假定了任意房子的总价格 35% 首付，65% 贷款。 但是贷款额度参考的基数其实是税务核定价格，这也就意味着 往往购买二手房，你的首付是要多交一笔的，是大于 35% 的 。这是为什么？我们简单做一下计算： 假设我们想购买的二手房网签总价为 $T_{网签}$ 元 ，且**假设税务核定价是网签价格的 85% **，此时税务核定价格 ： \[\begin{equation} \left\{ \begin{array}{lr} T_{贷款额度} = T_{核定} \times 65\% \notag \\ T_{核定} = T_{网签} \times 85\% \notag \\ \end{array} \\ \right. \end{equation}\] 带入后我们可以推导出： \[\begin{equation} \left\{ \begin{array}{lr} T_{贷款额度} = T_{网签} \times 55.25\% \notag \\ T_{首付} = 1-55.25\% = 44.75\% \notag \\ \end{array} \right. \end{equation}\] 根据我们的假设条件，我们发现首付我们必须要凑够 44.75% 价格的首付，而贷款额度只有 55.25%。 所以很多人都说，因为买了二手房，所以首付要高一些，将近 50%。其实就是上面这个原因。 增值税影响下的购房决策分析 同样的，我们假设网签总价为 $T_{网签}$ 元，且 假设税务核定价是网签价格的 85%。 另外，我从知乎上检索到这么一组数据 「2015-2019 年上海各区房价涨跌情况」。其中我需要用到各个区的二手房年化平均增长率，如下表总结： 区域 二手房价年化平均涨幅 区域 二手房价年化平均涨幅 长宁 13.30% 静安（包含老闸北） 16.04% 虹口 15.79% 闵行 14.02% 黄浦 15.99% 浦东（包含老南汇） 12.55% 普陀 15.81% 徐汇 13.55% 由上述数据我们可以计算出，上海二手房平均年化涨幅为 14.63%。有了涨幅数据之后，我们就可以求出差额的表达式，即 $T_{差额} = (税务核定价- 买入价格)$。当然，这里我们还要假设房屋年限为 $y$ 年 \[\begin{align} T_{差额} &amp;= T_{核定价} - T_{买入价格} \notag \\ \ &amp;= 0.85T_{网签} - T_{网签} \div (1 + 0.1463)^y \notag \\ \end{align}\] 接下来我们来计算增值税的表达式： 当房屋是普通住宅时： \[\begin{equation} T_{增值税} = \left\{ \begin{aligned} &amp; \frac{T_{核定价}}{1.05} \times 5.55\% = 0.04497 · T_{网签} &amp;&amp; (y &lt; 2)\\ &amp; 0 &amp;&amp; (y \geq 2) \end{aligned} \\ \right. \notag \\ \end{equation}\] 当房屋是非普通住宅时： \[\begin{equation} T_{增值税} = \left\{ \begin{aligned} &amp; 0.04497 · T_{网签} &amp;&amp; (y &lt; 2) \notag \\ \\ &amp; (0.85T_{网签} - \frac{T_{网签}}{(1 + 0.1463)^y}) \times 0.0529 &amp;&amp; (y \geq 2) \notag \\ \end{aligned} \right. \notag \\ \end{equation}\] 我们可以看到，当年限小于 2 年的时候，无论是普通住宅还是非普通住宅，其增值税都要支付将近 4.5% 的增值税。且是否是普通住宅对增值税毫无影响。 当年限大于等于 5 年的时候，普通住宅是免征增值税的，而非普通住宅是与年限和网签总价有一定关系的。我们来分析一下。 非普通住宅的年限影响 由于年份 $y$ 是离散的，所以我们将其投影在每一条折线上。以网签价格为横轴变量，来观察增值税与网签价的关系图： 我们可以得到以下结论： 房龄越高，其所得税缴纳越多。这也是可以理解的，因为随着房价的上涨，其差额会逐渐变大。 所得税的增长幅度与年限呈现下降趋势。随着年限增高，增长差值逐渐降低。 增值税占比 有没有什么方法来评估增值税最低的选择策略呢？我个人的想法是使用所占比例来考量。以下是我想的一个方法： \[P_{增值税所占比例} \approx \frac{T_{增值税}}{T_{网签价} + T_{增值税}}\] 为什么这里是约等于呢？因为最后你需要支出的价格除了网签价格外，不仅只有增值税，还有其他的各种税款。 这里仅仅使用增值税来当作基数，可以放大增值税的比重，更能体现问题。 作出图像我们可以发现，当我们购买“低龄”的房子，其所得税所占比例是更底的，5 年的二手房其所得税所占比例均值是 1.79%。 于是乎我们可以大致的计算出房龄与所得税所占比例的大致关系： 那么我们最好的策略是要选择最新的房子吗？其实并不是这样的，因为随着年限的增长，其单价也在逐渐升高。 换句话说，当我总价固定后，随着房龄的降低，其面积是越来越小的。房屋面积是和我们的需求息息相关的。 所以当我们做买房策略的时候，我们需要先确定需求面积和我们所支出的总价，然后尽可能的去购买新房就好了。 由于所得税在这里只能说明部分问题，具体的问题我将在后续的文中来具体分析。 总结 购买二手房时，首付高一些，将近 50%。 其原因是因为税务核算价往往偏低，从而拉低了贷款比重，进而使得首付提高； 当购买非普通住宅时，房龄越高，其所得税缴纳越多。因为随着房价的上涨，其差额会逐渐变大。 所得税的增长幅度与年限呈现下降趋势。随着年限增高，增长差值逐渐降低。 确定需求面积和所支出的总价，尽可能的去购买新房。这与我们的正常认知也是相同的。 相关数据分析代码 以下代码由我个人编写，可在 Jupyter Notebook 环境下直接运行。 """ 网签价与增值税 """ # encoding=utf-8 import numpy as np import math from matplotlib import pyplot import matplotlib.pyplot as plt from IPython.core.pylabtools import figsize # import figsize #figsize(12.5, 4) # 设置 figsize plt.rcParams['savefig.dpi'] = 300 #图片像素 plt.rcParams['figure.dpi'] = 300 #分辨率 # 总价 ths = [i * 125000 for i in range(1, 100)] # 年限 ys = [i for i in range(5, 21)] for y in ys: # 增值税计算 trs = [] for th in ths: tr = (0.85 * th - th / ((1 + 0.1463) ** y)) * 0.0529 trs.append(tr) plt.plot(ths, trs, label=f'{y}年') plt.legend() plt.margins(0) plt.subplots_adjust(bottom=0.10) plt.xlabel('网签价/千万元') #X轴标签 plt.ylabel("增值税/元") #Y轴标签 """ 网签价与增值税占比 """ # 年限 ys = [i for i in range(5, 21)] for y in ys: # 增值税计算 trs = [] for th in ths: tr = (0.85 * th - th / ((1 + 0.1463) ** y)) * 0.0529 trs.append(tr / (th + tr)) print(sum(trs) / len(trs)) if y &gt;= 10: plt.plot(ths, trs, label=f'{y}年') else: plt.plot(ths, trs, marker='*', label=f'{y}年') plt.legend() plt.margins(0) plt.subplots_adjust(bottom=0.10) plt.xlabel('网签价/千万元') #X轴标签 plt.ylabel("所得税占总支出比例") #Y轴标签 """ 房龄与增值税占比 """ p = [ 0.017910502320842965, 0.021189641628359904, 0.024032438906425032, 0.026498963556469416, 0.028640531033586977, 0.030501094013867885, 0.032118385667131544, 0.03352486519307519, 0.034748504347376426, 0.035813445129716175, 0.03674055234381547, 0.03754787981470654, 0.038251065262737784, 0.03886366589974932, 0.03939744452077101, 0.039862614060287876, ] plt.plot(p, y, marker='o') plt.legend() plt.margins(0) plt.xlabel('增值税占总支出比例') #X轴标签 plt.ylabel("房子年限/年") #Y轴标签]]></summary></entry><entry><title type="html">Podfile 的解析逻辑</title><link href="https://www.desgard.com/2020/09/16/cocoapods-story-4.html" rel="alternate" type="text/html" title="Podfile 的解析逻辑" /><published>2020-09-16T00:00:00-08:00</published><updated>2020-09-16T00:00:00-08:00</updated><id>https://www.desgard.com/2020/09/16/cocoapods-story-4</id><content type="html" xml:base="https://www.desgard.com/2020/09/16/cocoapods-story-4.html"><![CDATA[<h1 id="引子">引子</h1>

<p><br />在上文 <a href="/2020/09/02/cocoapods-story-3.html">CocoaPods 命令解析</a> 中，我们通过对 <strong>CLAide</strong> 的源码分析，了解了 CocoaPods 是如何处理 <code class="language-plaintext highlighter-rouge">pod</code> 命令，多级命令又是如何组织和嵌套的，并解释了命令行输出所代表的含义。今天我们开始学习 <code class="language-plaintext highlighter-rouge">Podfile</code> 。<br />
<br />大多 iOS 工程师最先接触到的 CocoaPods 概念应该是 <code class="language-plaintext highlighter-rouge">Podfile</code>，而 <code class="language-plaintext highlighter-rouge">Podfile</code> 属于 <code class="language-plaintext highlighter-rouge">cocoapods-core</code>（以下简称 <strong>Core</strong>） 的两大概念之一。另外一个则是 <a href="https://guides.cocoapods.org/syntax/podspec.html"><code class="language-plaintext highlighter-rouge">Podspec</code></a> (用于描述 Pod Library 的配置文件)，只有当你需要开发 Pod 组件的时候才会接触。<br />
<br />在介绍 Podfile 的内容结构之前，必须要谈谈 Xcode 的工程结构。
<a name="7ae87fa4"></a></p>
<h1 id="xcode-工程结构">Xcode 工程结构</h1>

<p><br />我们先来看一个极简 Podfile 声明：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">target</span> <span class="s1">'Demo'</span> <span class="k">do</span>
	<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:path</span> <span class="o">=&gt;</span> <span class="s1">'./Alamofire'</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />它编译后的工程目录如下：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1599993134156-fe45b615-5b0f-4e71-bd5c-a03cd6b55217.jpeg" alt="" /></p>

<p><br />如你所见 Podfile 的配置是围绕 Xcode 的这些工程结构：**Workspace、Project、Target 及 Build Setting **来展开的。<br />作为包管理工具 CocoaPods 将所管理的 Pods 依赖库组装成一个个 Target，统一放入 <code class="language-plaintext highlighter-rouge">Pods project</code> 中的 <code class="language-plaintext highlighter-rouge">Demo target</code>，并自动配置好 Target 间的依赖关系。<br />
<br />之后将 <code class="language-plaintext highlighter-rouge">Example</code> 主工程和 <code class="language-plaintext highlighter-rouge">Pods</code> 工程一起打包到新建的 <code class="language-plaintext highlighter-rouge">Example.workspace</code>，配好主工程与 <code class="language-plaintext highlighter-rouge">Pods</code> 工程之间的依赖，完成最终转换。<br />
<br />接下来，我们来聊一聊这些 Xcode 结构：<br /></p>

<p><a name="9f0655f1"></a></p>
<h2 id="target---最小可编译单元">Target - 最小可编译单元</h2>

<blockquote>
  <p>A <a href="https://developer.apple.com/library/archive/featuredarticles/XcodeConcepts/Concept-Targets.html#//apple_ref/doc/uid/TP40009328-CH4-SW1">target</a> specifies a product to build and contains the instructions for building the product from a set of files in a project or workspace.</p>
</blockquote>

<p><br /><strong>首先是 Target，它作为工程中最小的可编译单元，根据 **<a href="https://www.objc.io/issues/6-build-tools/build-process/#controlling-the-build-process">**Build Phases**</a></strong> 和 <strong><a href="https://developer.apple.com/library/archive/featuredarticles/XcodeConcepts/Concept-Build_Settings.html#//apple_ref/doc/uid/TP40009328-CH6-SW1">**Build Settings**</a></strong> 将源码作为输入，经编译后输出结果产物**。<br />其输出结果可以是链接库、可执行文件或者资源包等，具体细节如下：<br /></p>

<ul>
  <li>Build Setting：比如指定使用的编译器，目标平台、编译参数、头文件搜索路径等；</li>
  <li>Build 时的前置依赖、执行的脚本文件；</li>
  <li>Build 生成目标的签名、Capabilities 等属性；</li>
  <li>Input：哪些源码或者资源文件会被编译打包；</li>
  <li>Output：哪些静态库、动态库会被链接；</li>
</ul>

<p><a name="8fc0f046"></a></p>
<h2 id="project---targets-的载体">Project - Targets 的载体</h2>

<blockquote>
  <p>An <a href="https://developer.apple.com/library/archive/featuredarticles/XcodeConcepts/Concept-Projects.html#//apple_ref/doc/uid/TP40009328-CH5-SW1">Xcode project</a> is a repository for all the files, resources, and information required to build one or more software products.</p>
</blockquote>

<p><br /><strong>Project 就是一个独立的 Xcode 工程，作为一个或多个 Targets 的资源管理器，本身无法被编译。</strong><br />Project 所管理的资源都来自它所包含的 Targets。特点如下：<br /></p>

<ul>
  <li>至少包含一个或多个可编译的 Target；</li>
  <li>为所包含的 Targets 定义了一份默认编译选项，如果 Target 有自己的配置，则会覆盖 Project 的预设值；</li>
  <li>能将其他 Project 作为依赖嵌入其中；</li>
</ul>

<p><br />下图为 Project 与所包含对 Targets 的关系<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1600222941789-99a85a65-f93f-48ce-92c2-53b85c576bfd.jpeg" alt="" /></p>

<p><a name="be439828"></a></p>
<h2 id="workspace---容器">Workspace - 容器</h2>

<blockquote>
  <p>A <a href="https://developer.apple.com/library/archive/featuredarticles/XcodeConcepts/Concept-Workspace.html">workspace</a> is an Xcode document that groups projects</p>
</blockquote>

<p><br /><strong>作为纯粹的项目容器，Workspace 不参与任何编译链接过程，仅用于管理同层级的 Project</strong>，其特点：<br /></p>

<ul>
  <li><strong>Workspace 可以包含多个 Projects</strong>；</li>
  <li>同一个 Workspace 中的 Proejct 文件对于其他 Project 是默认可见的，<strong>这些 Projcts 会共享 <code class="language-plaintext highlighter-rouge">workspace build directory</code></strong> ；</li>
  <li>一个 Xcode Project 可以被包含在多个不同的 Workspace 中，因为每个 Project 都有独立的 Identity，默认是 Project Name；</li>
</ul>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1599993134181-70da3da0-70d6-46ff-b9ad-358e77f64466.jpeg" alt="" /></p>

<p><a name="db334362"></a></p>
<h2 id="scheme---描述-build-过程">Scheme - 描述 Build 过程</h2>

<blockquote>
  <p>An <a href="https://developer.apple.com/library/archive/featuredarticles/XcodeConcepts/Concept-Schemes.html">Xcode scheme</a> defines a collection of targets to build, a configuration to use when building, and a collection of tests to execute.</p>
</blockquote>

<p><br /><strong>Scheme 是对于整个 Build 过程的一个抽象</strong>，它描述了 Xcode 应该使用哪种 <a href="https://medium.com/practical-ios-development/some-practical-uses-for-xcode-build-schemes-and-build-configurations-swift-e50d15a1304f">Build Configurations</a> 、执行什么任务、环境参数等来构建我们所需的 Target。<br />
<br />Scheme 中预设了六个主要过程： <strong>Build、Run、Test、Profile、Analyze、Archive</strong>。包括了我们对 Target 的所有操作，每一个过程都可以单独配置。<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1600222941772-4998de2f-7375-4019-b665-77d5e7692c79.jpeg" alt="" /></p>

<p><a name="CocoaPods-Core"></a></p>
<h1 id="cocoapods-core">CocoaPods-Core</h1>

<blockquote>
  <p>The <a href="https://link.zhihu.com/?target=https%3A//github.com/CocoaPods/Core">CocoaPods-Core</a> gem provides support to work with the models of CocoaPods, for example the Podspecs or the Podfile.</p>
</blockquote>

<p><br />CocoaPods-Core 用于 CocoaPods 中配置文件的解析，包括 <code class="language-plaintext highlighter-rouge">Podfile</code>、<code class="language-plaintext highlighter-rouge">Podspec</code> 以及解析后的依赖锁存文件，如 Podfile.lock 等。<br /></p>

<p><a name="49aa38a1"></a></p>
<h2 id="cocoapods-core-的文件构成">CocoaPods-Core 的文件构成</h2>

<p><br />照例，我们先通过入口文件 <code class="language-plaintext highlighter-rouge">lib/cocoapods-core.rb</code> 来一窥 Core 项目的主要文件：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>
  <span class="nb">require</span> <span class="s1">'cocoapods-core/gem_version'</span>

  <span class="k">class</span> <span class="nc">PlainInformative</span> <span class="o">&lt;</span> <span class="no">StandardError</span><span class="p">;</span> <span class="k">end</span>
  <span class="k">class</span> <span class="nc">Informative</span> <span class="o">&lt;</span> <span class="no">PlainInformative</span><span class="p">;</span> <span class="k">end</span>

  <span class="nb">require</span> <span class="s1">'pathname'</span>
  <span class="nb">require</span> <span class="s1">'cocoapods-core/vendor'</span>
   
  <span class="c1"># 用于存储 PodSpec 中的版本号</span>
  <span class="nb">autoload</span> <span class="ss">:Version</span><span class="p">,</span>        <span class="s1">'cocoapods-core/version'</span>
  <span class="c1"># pod 的版本限制</span>
  <span class="nb">autoload</span> <span class="ss">:Requirement</span><span class="p">,</span>    <span class="s1">'cocoapods-core/requirement'</span>
  <span class="c1"># 配置 Podfile 或 PodSpec 中的 pod 依赖</span>
  <span class="nb">autoload</span> <span class="ss">:Dependency</span><span class="p">,</span>     <span class="s1">'cocoapods-core/dependency'</span>
  <span class="c1"># 获取 Github 仓库信息</span>
  <span class="nb">autoload</span> <span class="ss">:GitHub</span><span class="p">,</span>         <span class="s1">'cocoapods-core/github'</span>
  <span class="c1"># 处理 HTTP 请求</span>
  <span class="nb">autoload</span> <span class="ss">:HTTP</span><span class="p">,</span>           <span class="s1">'cocoapods-core/http'</span>
  <span class="c1"># 记录最终 pod 的依赖信息</span>
  <span class="nb">autoload</span> <span class="ss">:Lockfile</span><span class="p">,</span>       <span class="s1">'cocoapods-core/lockfile'</span>
  <span class="c1"># 记录 SDK 的名称和 target 版本</span>
  <span class="nb">autoload</span> <span class="ss">:Platform</span><span class="p">,</span>       <span class="s1">'cocoapods-core/platform'</span>
  <span class="c1"># 对应 Podfile 文件的 class</span>
  <span class="nb">autoload</span> <span class="ss">:Podfile</span><span class="p">,</span>        <span class="s1">'cocoapods-core/podfile'</span>
  <span class="c1"># 管理 PodSpec 的集合</span>
  <span class="nb">autoload</span> <span class="ss">:Source</span><span class="p">,</span>         <span class="s1">'cocoapods-core/source'</span>
  <span class="c1"># 管理基于 CDN 来源的 PodSpec 集合</span>
  <span class="nb">autoload</span> <span class="ss">:CDNSource</span><span class="p">,</span>      <span class="s1">'cocoapods-core/cdn_source'</span>
  <span class="c1"># 管理基于 Trunk 来源的 PodSpec 集合</span>
  <span class="nb">autoload</span> <span class="ss">:TrunkSource</span><span class="p">,</span>    <span class="s1">'cocoapods-core/trunk_source'</span>
  <span class="c1"># 对应 PodSpec 文件的 class</span>
  <span class="nb">autoload</span> <span class="ss">:Specification</span><span class="p">,</span>  <span class="s1">'cocoapods-core/specification'</span>
  <span class="c1"># 将 pod 信息转为 .yml 文件，用于 lockfile 的序列化</span>
  <span class="nb">autoload</span> <span class="ss">:YAMLHelper</span><span class="p">,</span>     <span class="s1">'cocoapods-core/yaml_helper'</span>
  <span class="c1"># 记录 pod 依赖类型，是静态库/动态库</span>
  <span class="nb">autoload</span> <span class="ss">:BuildType</span><span class="p">,</span>      <span class="s1">'cocoapods-core/build_type'</span>
  
  <span class="o">...</span>

  <span class="no">Spec</span> <span class="o">=</span> <span class="no">Specification</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />将这些 Model 类按照对应的依赖关系进行划分，层级如下：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1599993134206-3a7f8fdb-611d-44c1-a2c4-026365408d5e.jpeg" alt="" /></p>

<p><a name="7b11f844"></a></p>
<h2 id="podfile-的主要数据结构">Podfile 的主要数据结构</h2>

<p><br />先来了解 Podfile 的主要数据结构<br /></p>

<p><a name="Specification"></a></p>
<h3 id="specification">Specification</h3>

<blockquote>
  <p>The Specification provides a DSL to describe a Pod. A pod is defined as a library originating from a source. A specification can support detailed attributes for modules of code  through subspecs.</p>
</blockquote>

<p><br />Specification 即存储 <code class="language-plaintext highlighter-rouge">PodSpec</code> 的内容，是用于<strong>描述一个 Pod 库的源代码和资源将如何被打包编译成链接库或 framework</strong>，后续将会介绍更多的细节。<br /></p>

<p><a name="TargetDefinition"></a></p>
<h3 id="targetdefinition">TargetDefinition</h3>

<blockquote>
  <p>The TargetDefinition stores the information of a CocoaPods static library. The target definition can be linked with one or more targets of the user project.</p>
</blockquote>

<p><br /><code class="language-plaintext highlighter-rouge">TargetDefinition</code> 是一个多叉树结构，每个节点记录着 <code class="language-plaintext highlighter-rouge">Podfile</code> 中定义的 Pod 的 Source 来源、Build Setting、Pod 子依赖等。该树的根节点指向 <code class="language-plaintext highlighter-rouge">Podfile</code>，而 <code class="language-plaintext highlighter-rouge">Podfile</code> 中的 <code class="language-plaintext highlighter-rouge">root_target_definitions</code> 则记录着所有的 <code class="language-plaintext highlighter-rouge">TargetDefinition</code> 的根节点，正常情况下该 list 中只有一个 root 即 <code class="language-plaintext highlighter-rouge">**Pods.project**</code>。<br />
<br />为了便于阅读，简化了大量的 DSL 配置相关的方法和属性并对代码顺序做了调整，大致结构如下：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Podfile</span>
    <span class="k">class</span> <span class="nc">TargetDefinition</span>
		<span class="c1"># 父节点: TargetDefinition 或者 Podfile</span>
      <span class="nb">attr_reader</span> <span class="ss">:parent</span>
      <span class="c1"># 子节点: TargetDefinition</span>
      <span class="nb">attr_reader</span> <span class="ss">:children</span>
      <span class="c1"># 记录 tareget 的配置信息</span>
      <span class="nb">attr_accessor</span> <span class="ss">:internal_hash</span>

      <span class="k">def</span> <span class="nf">root?</span>
        <span class="n">parent</span><span class="p">.</span><span class="nf">is_a?</span><span class="p">(</span><span class="no">Podfile</span><span class="p">)</span> <span class="o">||</span> <span class="n">parent</span><span class="p">.</span><span class="nf">nil?</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">root</span>
        <span class="k">if</span> <span class="n">root?</span>
          <span class="nb">self</span>
        <span class="k">else</span>
          <span class="n">parent</span><span class="p">.</span><span class="nf">root</span>
        <span class="k">end</span>
      <span class="k">end</span>

      <span class="k">def</span> <span class="nf">podfile</span>
        <span class="n">root</span><span class="p">.</span><span class="nf">parent</span>
      <span class="k">end</span>
       
      <span class="c1"># ...</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />对应上一节 Xcode 工程结构中的 <code class="language-plaintext highlighter-rouge">Podfile</code> 关系如下：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1599993134189-fdfc2639-938d-47c7-ad69-1a8141502f8f.jpeg" alt="" /></p>

<p><br />CocoaPods 正是巧妙利用了 Xcode 工程结构的特点，引入  <code class="language-plaintext highlighter-rouge">Pods.project</code> 这一中间层，将主工程的 Pods 依赖全部转接到 <code class="language-plaintext highlighter-rouge">Pods.project</code> 上，最后再将 <code class="language-plaintext highlighter-rouge">Pods.project</code> 作为主项目的依赖。尽管这么做也受到了一些质疑和诟病（所谓的侵入性太强），但笔者的观点是，正得益于 <code class="language-plaintext highlighter-rouge">Pods.project</code> 这一设计隔绝了第三方依赖库对于主项目的频繁更改，也便于后续的管理和更新，体现了软件工程中的<strong>开放-关闭原则</strong>。<br />
<br />比如，在 Pod 1.7.0 版本中支持的 <strong><a href="http://blog.cocoapods.org/CocoaPods-1.7.0-beta/">Multiple Xcodeproj Generation</a></strong> 就是解决随着项目的迭代而日益增大的 <code class="language-plaintext highlighter-rouge">Pods</code> project 的问题。试想当你的项目中存在上百个依赖库，每个依赖库的变更都会影响到你的主工程，这将是非常可怕的问题。<br /></p>

<p><a name="Podfile"></a></p>
<h3 id="podfile">Podfile</h3>

<blockquote>
  <p>The Podfile is a specification that describes the dependencies of the targets of one or more Xcode projects.</p>
</blockquote>

<p><br /><code class="language-plaintext highlighter-rouge">Podfile</code> 是用于描述一个或多个 Xcode Project 中各个 Targets 之间的依赖关系。<br />
<br />这些 Targets 的依赖关系对应的就是 <code class="language-plaintext highlighter-rouge">TargetDefinition</code> 树中的各子节点的层级关系。如前面所说，<strong>有了 <code class="language-plaintext highlighter-rouge">Podfile</code> 这个根节点的指向，仅需对依赖树进行遍历，就能轻松获取完整的依赖关系</strong>。<br />
<br />有了这层依赖树，对于某个 <code class="language-plaintext highlighter-rouge">Pod</code> 库的更新即是对树节点的更新，便可轻松的分析出此次更新涉及的影响。<br />
<br />简化调整后的 Podfile 代码如下：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">require</span> <span class="s1">'cocoapods-core/podfile/dsl'</span>
<span class="nb">require</span> <span class="s1">'cocoapods-core/podfile/target_definition'</span>

<span class="k">module</span> <span class="nn">Pod</span>
  <span class="k">class</span> <span class="nc">Podfile</span>

    <span class="kp">include</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Podfile</span><span class="o">::</span><span class="no">DSL</span>
    <span class="c1"># podfile 路径</span>
    <span class="nb">attr_accessor</span> <span class="ss">:defined_in_file</span>
    <span class="c1"># 所有的 TargetDefinition 的根节点, 正常只有一个，即 Pods.project target</span>
    <span class="nb">attr_accessor</span> <span class="ss">:root_target_definitions</span>
    <span class="c1"># 记录 Pods.project 项目的配置信息</span>
    <span class="nb">attr_accessor</span> <span class="ss">:internal_hash</span>
    <span class="c1"># 当前 DSL 解析使用的 TargetDefinition</span>
    <span class="nb">attr_accessor</span> <span class="ss">:current_target_definition</span>

    <span class="c1"># ...</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />直接看 <code class="language-plaintext highlighter-rouge">dsl.rb</code>，该文件内部定义了 Podfile DSL 支持的所有方法。通过 <strong>include</strong> 的使用将 <code class="language-plaintext highlighter-rouge">Pod::Podfile::DSL</code> 模块 Mix-in 后插入到 Podfile 类中。<br />想了解更多 Mix-in 特性，移步 <a href="https://mp.weixin.qq.com/s?__biz=MzA5MTM1NTc2Ng==&amp;mid=2458324049&amp;idx=1&amp;sn=8de53f46fbc52427cdb660b427cb8226&amp;chksm=870e0348b0798a5ed6d14715cc4a1af93cd168a5e15198acfb3b84ea49506b0f815fa891d683&amp;token=883887783&amp;lang=zh_CN#rd">Ruby 特性之 Mix-in</a>。<br /></p>

<p><a name="Lockfile"></a></p>
<h3 id="lockfile">Lockfile</h3>

<blockquote>
  <p>The Lockfile stores information about the pods that were installed by  CocoaPods.</p>
</blockquote>

<p><br /><strong>Lockfile，顾名思义是用于记录最后一次 CocoaPods 所安装的 Pod 依赖库版本的信息快照。也就是生成的 **<code class="language-plaintext highlighter-rouge">Podfile.lock</code></strong>。**<br />
<br />在 <code class="language-plaintext highlighter-rouge">pod install</code> 过程，Podfile 会结合它来确认最终所安装的 Pod 版本，固定 Pod 依赖库版本防止其自动更新。Lockfile 也作为 Pods 状态清单 (mainfest)，用于记录安装过程的中哪些 Pod 需要被删除或安装或更新等。<br />
<br />以开头的 Podfile 经 <code class="language-plaintext highlighter-rouge">pod install</code> 所生成的 <code class="language-plaintext highlighter-rouge">Podfile.lock</code> 为例：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">PODS</span><span class="p">:</span>
  <span class="o">-</span> <span class="no">Alamofire</span> <span class="p">(</span><span class="mf">4.6</span><span class="o">.</span><span class="mi">0</span><span class="p">)</span>

<span class="no">DEPENDENCIES</span><span class="p">:</span>
  <span class="o">-</span> <span class="no">Alamofire</span> <span class="p">(</span><span class="n">from</span> <span class="sb">`./Alamofire`</span><span class="p">)</span>

<span class="no">EXTERNAL</span> <span class="no">SOURCES</span><span class="p">:</span>
  <span class="no">Alamofire</span><span class="p">:</span>
    <span class="ss">:path</span><span class="p">:</span> <span class="s2">"./Alamofire"</span>

<span class="no">SPEC</span> <span class="no">CHECKSUMS</span><span class="p">:</span>
  <span class="no">Alamofire</span><span class="p">:</span> <span class="mi">0</span><span class="n">dda98a0ed7eec4bdcd5fe3cdd35fcd2b3022825</span>

<span class="no">PODFILE</span> <span class="no">CHECKSUM</span><span class="p">:</span> <span class="n">da12cc12a30cfb48ebc5d14e8f51737ab65e8241</span>

<span class="no">COCOAPODS</span><span class="p">:</span> <span class="mf">1.10</span><span class="o">.</span><span class="mi">0</span><span class="p">.</span><span class="nf">beta</span><span class="o">.</span><span class="mi">2</span>
</code></pre></div></div>

<p><br />我们来分析一下，通过该 Lockfile 能够获取哪些信息：</p>

<table>
  <thead>
    <tr>
      <th><strong>Key</strong></th>
      <th><strong>含义</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>PODS</strong></td>
      <td>记录所有 Pod 库的具体安装版本号</td>
    </tr>
    <tr>
      <td><strong>DEPENDENCIES</strong></td>
      <td>记录各 Pod 库之间的相互依赖关系，由于这里只有 Alamofire 且它无其他依赖，暂时无关看出区别</td>
    </tr>
    <tr>
      <td><strong>EXTERNAL SOURCES</strong></td>
      <td>记录部分通过外部源的 Pod 库（Git 引入、Path 引入）</td>
    </tr>
    <tr>
      <td><strong>SPEC CHECKSUMS</strong></td>
      <td>记录当前各 Pod 库的 Podspec 文件 Hash 值，其实就是文件的 md5</td>
    </tr>
    <tr>
      <td><strong>PODFILE CHECKSUM</strong></td>
      <td>记录 Podfile 文件的 Hash 值，同样是 md5，确认是否有变更</td>
    </tr>
    <tr>
      <td><strong>COCOAPODS</strong></td>
      <td>记录上次所使用的 CocoaPods 版本</td>
    </tr>
  </tbody>
</table>

<p><a name="80b7b70d"></a></p>
<h2 id="podfile-内容加载">Podfile 内容加载</h2>

<p><a name="8d8c5129"></a></p>
<h3 id="podfile-文件类型">Podfile 文件类型</h3>

<p><br />你可以在 CocoaPods 的 <code class="language-plaintext highlighter-rouge">/lib/cocoapods/config.rb</code> 找到 Podfile 所支持的文件类型：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">PODFILE_NAMES</span> <span class="o">=</span> <span class="p">[</span>
   <span class="s1">'CocoaPods.podfile.yaml'</span><span class="p">,</span>
   <span class="s1">'CocoaPods.podfile'</span><span class="p">,</span>
   <span class="s1">'Podfile'</span><span class="p">,</span>
   <span class="s1">'Podfile.rb'</span><span class="p">,</span>
<span class="p">].</span><span class="nf">freeze</span>
</code></pre></div></div>

<p><br />CocoaPods 按照上述命名优先级来查找工程目录下所对应的 Podfile 文件。当发现目录中存在 <strong>CocoaPods.podfile.yaml</strong> 文件时会优先加载。很多同学可能只知道到 Podfile 支持 Ruby 的文件格式，而不了解它还支持了 YAML 格式。YAML 是 <code class="language-plaintext highlighter-rouge">YAML Ain't Markup Language</code> 的缩写，其 <a href="https://yaml.org/">官方定义</a>：<br /></p>

<blockquote>
  <p>YAML is a human friendly data serialization standard for all programming languages.</p>
</blockquote>

<p><br />它是一种面向工程师友好的序列化语言。我们的 Lockfile 文件就是以 YAML 格式写入 <code class="language-plaintext highlighter-rouge">Podfile.lock</code> 中的。<br /></p>

<p><a name="93616363"></a></p>
<h3 id="podfile-文件读取">Podfile 文件读取</h3>

<p><br />回到 <code class="language-plaintext highlighter-rouge">lib/cocoapods-core/podfile.rb</code> 来看读取方法：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">module</span> <span class="nn">Pod</span>

  <span class="k">class</span> <span class="nc">Podfile</span>

    <span class="kp">include</span> <span class="no">Pod</span><span class="o">::</span><span class="no">Podfile</span><span class="o">::</span><span class="no">DSL</span>

    <span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_file</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
      <span class="n">path</span> <span class="o">=</span> <span class="no">Pathname</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
      <span class="k">unless</span> <span class="n">path</span><span class="p">.</span><span class="nf">exist?</span>
        <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"No Podfile exists at path `</span><span class="si">#{</span><span class="n">path</span><span class="si">}</span><span class="s2">`."</span>
      <span class="k">end</span>
			<span class="c1"># 这里我们可以看出，Podfile 目前已经支持了结尾是 .podfile 和 .rb 后缀的文件名</span>
      <span class="c1"># 其实是为了改善很多编译器使用文件后缀来确认 filetype，比如 vim</span>
      <span class="c1"># 相比与 Podfile 这个文件名要更加的友好</span>
      <span class="k">case</span> <span class="n">path</span><span class="p">.</span><span class="nf">extname</span>
      <span class="k">when</span> <span class="s1">''</span><span class="p">,</span> <span class="s1">'.podfile'</span><span class="p">,</span> <span class="s1">'.rb'</span>
        <span class="no">Podfile</span><span class="p">.</span><span class="nf">from_ruby</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
      <span class="k">when</span> <span class="s1">'.yaml'</span>
        <span class="c1"># 现在也支持了 .yaml 格式</span>
        <span class="no">Podfile</span><span class="p">.</span><span class="nf">from_yaml</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
      <span class="k">else</span>
        <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"Unsupported Podfile format `</span><span class="si">#{</span><span class="n">path</span><span class="si">}</span><span class="s2">`."</span>
      <span class="k">end</span>
    <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br /><code class="language-plaintext highlighter-rouge">from_file</code> 在 <code class="language-plaintext highlighter-rouge">pod install</code> 命令执行后的 <code class="language-plaintext highlighter-rouge">verify_podfile_exists!</code> 中被调用的：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">verify_podfile_exists!</span>
    <span class="k">unless</span> <span class="n">config</span><span class="p">.</span><span class="nf">podfile</span>
        <span class="k">raise</span> <span class="no">Informative</span><span class="p">,</span> <span class="s2">"No `Podfile' found in the project directory."</span>
    <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />而 Podfile 文件的读取就是 <code class="language-plaintext highlighter-rouge">config.podfile</code>  里触发的，代码在 CocoaPods 的 <code class="language-plaintext highlighter-rouge">config.rb</code> 文件中：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">podfile_path_in_dir</span><span class="p">(</span><span class="n">dir</span><span class="p">)</span>
    <span class="no">PODFILE_NAMES</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">filename</span><span class="o">|</span>
        <span class="n">candidate</span> <span class="o">=</span> <span class="n">dir</span> <span class="o">+</span> <span class="n">filename</span>
        <span class="k">if</span> <span class="n">candidate</span><span class="p">.</span><span class="nf">file?</span>
        <span class="k">return</span> <span class="n">candidate</span>
        <span class="k">end</span>
    <span class="k">end</span>
    <span class="kp">nil</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">podfile_path</span>
    <span class="vi">@podfile_path</span> <span class="o">||=</span> <span class="n">podfile_path_in_dir</span><span class="p">(</span><span class="n">installation_root</span><span class="p">)</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">podfile</span>
    <span class="vi">@podfile</span> <span class="o">||=</span> <span class="no">Podfile</span><span class="p">.</span><span class="nf">from_file</span><span class="p">(</span><span class="n">podfile_path</span><span class="p">)</span> <span class="k">if</span> <span class="n">podfile_path</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />这里的方法 <code class="language-plaintext highlighter-rouge">podfile</code> 和 <code class="language-plaintext highlighter-rouge">podfile_path</code> 都是 lazy 加载的。最后 Core 的 <code class="language-plaintext highlighter-rouge">from_file</code> 将依据目录下的 <code class="language-plaintext highlighter-rouge">Podfile</code> 文件类型选择调用 <code class="language-plaintext highlighter-rouge">from_yaml</code> 或者 <code class="language-plaintext highlighter-rouge">from_ruby</code>。<br />
<br />从 <code class="language-plaintext highlighter-rouge">Pod::Command::Install</code> 命令到 Podfile 文件加载的调用栈如下：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1599993134203-782e510d-c084-4b57-98fe-970f5a38cc79.jpeg" alt="" /></p>

<p><a name="28797697"></a></p>
<h3 id="podfile-from-ruby-解析">Podfile From Ruby 解析</h3>

<p><br />当我们通过 <code class="language-plaintext highlighter-rouge">pod init</code> 来初始化 CocoaPods 项目时，默认生成的 Podfile 名称就是 <code class="language-plaintext highlighter-rouge">Podfile</code>，那就从 <code class="language-plaintext highlighter-rouge">Podfile.from_ruby</code> 开始。<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_ruby</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">contents</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
    <span class="c1"># ①</span>
    <span class="n">contents</span> <span class="o">||=</span> <span class="no">File</span><span class="p">.</span><span class="nf">open</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s1">'r:utf-8'</span><span class="p">,</span> <span class="o">&amp;</span><span class="ss">:read</span><span class="p">)</span>
    <span class="c1"># 兼容 1.9 版本的 Rubinius 中的编码问题</span>
    <span class="k">if</span> <span class="n">contents</span><span class="p">.</span><span class="nf">respond_to?</span><span class="p">(</span><span class="ss">:encoding</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="n">contents</span><span class="p">.</span><span class="nf">encoding</span><span class="p">.</span><span class="nf">name</span> <span class="o">!=</span> <span class="s1">'UTF-8'</span>
        <span class="n">contents</span><span class="p">.</span><span class="nf">encode!</span><span class="p">(</span><span class="s1">'UTF-8'</span><span class="p">)</span>
    <span class="k">end</span>

    <span class="c1"># 对 Podfile 中不规范的单引号或双引号进行检查，并进行自动修正，及抛出错误</span>
    <span class="k">if</span> <span class="n">contents</span><span class="p">.</span><span class="nf">tr!</span><span class="p">(</span><span class="s1">'“”‘’‛'</span><span class="p">,</span> <span class="sx">%(""''')</span><span class="p">)</span>
        <span class="no">CoreUI</span><span class="p">.</span><span class="nf">warn</span> <span class="s2">"..."</span>
    <span class="k">end</span>
    <span class="c1"># ②</span>
    <span class="n">podfile</span> <span class="o">=</span> <span class="no">Podfile</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">path</span><span class="p">)</span> <span class="k">do</span>
        <span class="k">begin</span>
	        <span class="nb">eval</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="kp">nil</span><span class="p">,</span> <span class="n">path</span><span class="p">.</span><span class="nf">to_s</span><span class="p">)</span>
        <span class="k">rescue</span> <span class="no">Exception</span> <span class="o">=&gt;</span> <span class="n">e</span>
	        <span class="n">message</span> <span class="o">=</span> <span class="s2">"Invalid `</span><span class="si">#{</span><span class="n">path</span><span class="p">.</span><span class="nf">basename</span><span class="si">}</span><span class="s2">` file: </span><span class="si">#{</span><span class="n">e</span><span class="p">.</span><span class="nf">message</span><span class="si">}</span><span class="s2">"</span>
   	     <span class="k">raise</span> <span class="no">DSLError</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">message</span><span class="p">,</span> <span class="n">path</span><span class="p">,</span> <span class="n">e</span><span class="p">,</span> <span class="n">contents</span><span class="p">)</span>
        <span class="k">end</span>
    <span class="k">end</span>
    <span class="n">podfile</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br /><strong>①</strong> 是对 Podfile 内容的读取和编码，同时对可能出现的单引号和双引号的匹配问题进行了修正。<br /><strong>②</strong> 以 <code class="language-plaintext highlighter-rouge">path</code> 和 <code class="language-plaintext highlighter-rouge">block</code> 为入参进行 <code class="language-plaintext highlighter-rouge">podfile</code> 类的初始化并将其放回，保存在全局的 <code class="language-plaintext highlighter-rouge">config.podfile</code> 中。<br /></p>

<blockquote>
  <p>Tips: 如果要在 Ruby 对象的初始化中传入参数，需要重载 Object 的 <a href="https://ruby-doc.org/docs/ruby-doc-bundle/UsersGuide/rg/objinitialization.html">initialize</a> 方法，这里的 Podfile.new(…) 本质上是 <code class="language-plaintext highlighter-rouge">initialize</code> 的方法调用。</p>
</blockquote>

<p><br /><code class="language-plaintext highlighter-rouge">initialize</code> 方法所传入的尾随闭包 <code class="language-plaintext highlighter-rouge">block</code> 的核心在于内部的 <code class="language-plaintext highlighter-rouge">eval</code> 函数（在 <a href="https://zhuanlan.zhihu.com/p/187272448">CocoaPods 核心组件</a> 中有提到）：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="nb">eval</span><span class="p">(</span><span class="n">contents</span><span class="p">,</span> <span class="kp">nil</span><span class="p">,</span> <span class="n">path</span><span class="p">.</span><span class="nf">to_s</span><span class="p">)</span>
</code></pre></div></div>

<p><br />它将 Podfile 中的文本内容转化为方法执行，也就是说里面的参数是一段 Ruby 的代码字符串，通过 <code class="language-plaintext highlighter-rouge">eval</code> 方法可以直接执行。<br />继续看 Podfile 的 <code class="language-plaintext highlighter-rouge">initialize</code> 方法：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">defined_in_file</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">,</span> <span class="n">internal_hash</span> <span class="o">=</span> <span class="p">{},</span> <span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
    <span class="nb">self</span><span class="p">.</span><span class="nf">defined_in_file</span> <span class="o">=</span> <span class="n">defined_in_file</span>
    <span class="vi">@internal_hash</span> <span class="o">=</span> <span class="n">internal_hash</span>
    <span class="k">if</span> <span class="n">block</span>
        <span class="n">default_target_def</span> <span class="o">=</span> <span class="no">TargetDefinition</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="s1">'Pods'</span><span class="p">,</span> <span class="nb">self</span><span class="p">)</span>
        <span class="n">default_target_def</span><span class="p">.</span><span class="nf">abstract</span> <span class="o">=</span> <span class="kp">true</span>
        <span class="vi">@root_target_definitions</span> <span class="o">=</span> <span class="p">[</span><span class="n">default_target_def</span><span class="p">]</span>
        <span class="vi">@current_target_definition</span> <span class="o">=</span> <span class="n">default_target_def</span>
        <span class="nb">instance_eval</span><span class="p">(</span><span class="o">&amp;</span><span class="n">block</span><span class="p">)</span>
    <span class="k">else</span>
        <span class="vi">@root_target_definitions</span> <span class="o">=</span> <span class="p">[]</span>
    <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />它定义了三个参数：</p>

<table>
  <thead>
    <tr>
      <th>参数</th>
      <th>定义</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><strong>defined_in_file</strong></td>
      <td><code class="language-plaintext highlighter-rouge">Podfile</code> 文件路径</td>
    </tr>
    <tr>
      <td><strong>internal_hash</strong></td>
      <td>通过 yaml 序列化得到的 <code class="language-plaintext highlighter-rouge">Podfile</code> 配置信息，保存在 <code class="language-plaintext highlighter-rouge">internal_hash</code> 中</td>
    </tr>
    <tr>
      <td><strong>block</strong></td>
      <td>用于映射 <code class="language-plaintext highlighter-rouge">Podfile</code> 的 DSL 配置</td>
    </tr>
  </tbody>
</table>

<blockquote>
  <p>需要注意的是，通过 <code class="language-plaintext highlighter-rouge">from_ruby</code> 初始化的 <code class="language-plaintext highlighter-rouge">Podfile</code> 只传入了参数 1 和 3，参数 2 <code class="language-plaintext highlighter-rouge">internal_hash</code> 则是提供给 <code class="language-plaintext highlighter-rouge">from_yaml</code> 的。</p>
</blockquote>

<p><br />当 <code class="language-plaintext highlighter-rouge">block</code> 存在，会初始化名为 <code class="language-plaintext highlighter-rouge">Pods</code> 的 TargetDefinition 对象，用于保存 <code class="language-plaintext highlighter-rouge">Pods project</code> 的相关信息和 Pod 依赖。然后调用 <em><a href="https://ruby-doc.org/core-2.7.0/BasicObject.html">instance_eval</a></em> 执行传入的 <code class="language-plaintext highlighter-rouge">block</code>，将 Podfile 的 DSL 内容转换成对应的方法和参数，最终将参数存入 <code class="language-plaintext highlighter-rouge">internal_hash</code> 和对应的 <code class="language-plaintext highlighter-rouge">target_definitions</code> 中。<br /></p>

<blockquote>
  <p>Tips: 在 Ruby 中存在两种不同的方式来执行代码块 <code class="language-plaintext highlighter-rouge">block</code>，分别是 <code class="language-plaintext highlighter-rouge">instance_eval</code> 和 <code class="language-plaintext highlighter-rouge">class_eval</code>。
<code class="language-plaintext highlighter-rouge">class_eval</code> 的执行上下文与调用类相关，调用者是类名或者模块名，而 <code class="language-plaintext highlighter-rouge">instance_eval</code> 的调用者可以是类的实例或者类本身。细节看 <a href="https://stackoverflow.com/questions/900419/how-to-understand-the-difference-between-class-eval-and-instance-eval">StackoverFlow</a>。</p>
</blockquote>

<p><a name="434ab4f0"></a></p>
<h3 id="podfile-from-yaml-解析">Podfile From YAML 解析</h3>

<p><br />YAML 格式的 Podfile 加载需要借助 <strong>YAMLHelper</strong> 类来完成，YAMLHelper 则是基于 <a href="https://github.com/ruby/yaml">yaml</a> 的简单封装。<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_yaml</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
    <span class="n">string</span> <span class="o">=</span> <span class="no">File</span><span class="p">.</span><span class="nf">open</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="s1">'r:utf-8'</span><span class="p">,</span> <span class="o">&amp;</span><span class="ss">:read</span><span class="p">)</span>
  
    <span class="c1"># 为了解决 Rubinius incomplete encoding in 1.9 mode</span>
  	<span class="c1"># https://github.com/rubinius/rubinius/issues/1539</span>
    <span class="k">if</span> <span class="n">string</span><span class="p">.</span><span class="nf">respond_to?</span><span class="p">(</span><span class="ss">:encoding</span><span class="p">)</span> <span class="o">&amp;&amp;</span> <span class="n">string</span><span class="p">.</span><span class="nf">encoding</span><span class="p">.</span><span class="nf">name</span> <span class="o">!=</span> <span class="s1">'UTF-8'</span>
        <span class="n">string</span><span class="p">.</span><span class="nf">encode!</span><span class="p">(</span><span class="s1">'UTF-8'</span><span class="p">)</span>
    <span class="k">end</span>
    <span class="nb">hash</span> <span class="o">=</span> <span class="no">YAMLHelper</span><span class="p">.</span><span class="nf">load_string</span><span class="p">(</span><span class="n">string</span><span class="p">)</span>
    <span class="n">from_hash</span><span class="p">(</span><span class="nb">hash</span><span class="p">,</span> <span class="n">path</span><span class="p">)</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">from_hash</span><span class="p">(</span><span class="nb">hash</span><span class="p">,</span> <span class="n">path</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
    <span class="n">internal_hash</span> <span class="o">=</span> <span class="nb">hash</span><span class="p">.</span><span class="nf">dup</span>
    <span class="n">target_definitions</span> <span class="o">=</span> <span class="n">internal_hash</span><span class="p">.</span><span class="nf">delete</span><span class="p">(</span><span class="s1">'target_definitions'</span><span class="p">)</span> <span class="o">||</span> <span class="p">[]</span>
    <span class="n">podfile</span> <span class="o">=</span> <span class="no">Podfile</span><span class="p">.</span><span class="nf">new</span><span class="p">(</span><span class="n">path</span><span class="p">,</span> <span class="n">internal_hash</span><span class="p">)</span>
    <span class="n">target_definitions</span><span class="p">.</span><span class="nf">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">definition_hash</span><span class="o">|</span>
        <span class="n">definition</span> <span class="o">=</span> <span class="no">TargetDefinition</span><span class="p">.</span><span class="nf">from_hash</span><span class="p">(</span><span class="n">definition_hash</span><span class="p">,</span> <span class="n">podfile</span><span class="p">)</span>
        <span class="n">podfile</span><span class="p">.</span><span class="nf">root_target_definitions</span> <span class="o">&lt;&lt;</span> <span class="n">definition</span>
    <span class="k">end</span>
    <span class="n">podfile</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />通过 <code class="language-plaintext highlighter-rouge">from_yaml</code> 将文件内容转成 Ruby hash 后转入 <code class="language-plaintext highlighter-rouge">from_hash</code> 方法。<br />
<br />区别于 <code class="language-plaintext highlighter-rouge">from_ruby</code>，这里调用的 <code class="language-plaintext highlighter-rouge">initialize</code> 将读取的 hash 直接存入 <code class="language-plaintext highlighter-rouge">internal_hash</code>，然后利用 <code class="language-plaintext highlighter-rouge">TargetDefinition.from_hash</code> 来完成的 hash 内容到 targets 的转换，因此，这里无需传入 block 进行 DSL 解析和方法转换。<br /></p>

<p><a name="32e84827"></a></p>
<h2 id="podfile-内容解析">Podfile 内容解析</h2>

<p><br />前面提到 Podfile 的内容最终保存在 <code class="language-plaintext highlighter-rouge">internal_hash</code> 和 <code class="language-plaintext highlighter-rouge">target_definitions</code> 中，本质上都是使用了 <code class="language-plaintext highlighter-rouge">hash</code> 来保存数据。由于 YAML 文件格式的 Podfile 加载后就是 hash 对象，无需过多加工。唯一需要处理的是递归调用 TargetDefinition 的 <code class="language-plaintext highlighter-rouge">from_hash</code> 方法来解析 target 子节点的数据。<br />
<br />因此，接下来的内容解析主要针对 Ruby 文件格式的 DSL 解析，我们以 <code class="language-plaintext highlighter-rouge">pod</code> 方法为例：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">target</span> <span class="s1">'Example'</span> <span class="k">do</span>
	<span class="n">pod</span> <span class="s1">'Alamofire'</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />当解析到 <code class="language-plaintext highlighter-rouge">pod 'Alamofire'</code> 时，会先通过 <code class="language-plaintext highlighter-rouge">eval(contents, nil, path.to_s</code> 将其转换为 <code class="language-plaintext highlighter-rouge">dsl.rb</code> 中的方法：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">pod</span><span class="p">(</span><span class="nb">name</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">,</span> <span class="o">*</span><span class="n">requirements</span><span class="p">)</span>
    <span class="k">unless</span> <span class="nb">name</span>
        <span class="k">raise</span> <span class="no">StandardError</span><span class="p">,</span> <span class="s1">'A dependency requires a name.'</span>
    <span class="k">end</span>
    <span class="n">current_target_definition</span><span class="p">.</span><span class="nf">store_pod</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="o">*</span><span class="n">requirements</span><span class="p">)</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />name 为 Alamofire，由于我们没有指定对应的 Alamofire 版本，默认会使用最新版本。<code class="language-plaintext highlighter-rouge">requirements</code>  是控制 该 pod 来源获取或者 pod target 的编译选项等，例如：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="s1">'0.9'</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:modular_headers</span> <span class="o">=&gt;</span> <span class="kp">true</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:configurations</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">'Debug'</span><span class="p">,</span> <span class="s1">'Beta'</span><span class="p">]</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:source</span> <span class="o">=&gt;</span> <span class="s1">'https://github.com/CocoaPods/Specs.git'</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:subspecs</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">'Attribute'</span><span class="p">,</span> <span class="s1">'QuerySet'</span><span class="p">]</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:testspecs</span> <span class="o">=&gt;</span> <span class="p">[</span><span class="s1">'UnitTests'</span><span class="p">,</span> <span class="s1">'SomeOtherTests'</span><span class="p">]</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:path</span> <span class="o">=&gt;</span> <span class="s1">'~/Documents/AFNetworking'</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:podspec</span> <span class="o">=&gt;</span> <span class="s1">'https://example.com/Alamofire.podspec'</span>
<span class="n">pod</span> <span class="s1">'Alamofire'</span><span class="p">,</span> <span class="ss">:git</span> <span class="o">=&gt;</span> <span class="s1">'https://github.com/looseyi/Alamofire.git'</span><span class="p">,</span> <span class="ss">:tag</span> <span class="o">=&gt;</span> <span class="s1">'0.7.0'</span>
</code></pre></div></div>

<blockquote>
  <p>Tips：requirements 最终是以 Gem::Requirement 对象来保存的。关于 pod 详细说明请移步：<a href="https://guides.cocoapods.org/syntax/podfile.html#pod">Podfile 手册</a>。</p>
</blockquote>

<p><br />对 name 进行校验后，直接转入 <code class="language-plaintext highlighter-rouge">current_target_definition</code> 毕竟 Pod 库都是存在 <code class="language-plaintext highlighter-rouge">Pods.project</code> 之下：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="k">def</span> <span class="nf">store_pod</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="o">*</span><span class="n">requirements</span><span class="p">)</span>
  <span class="k">return</span> <span class="k">if</span> <span class="n">parse_subspecs</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">requirements</span><span class="p">)</span> <span class="c1"># This parse method must be called first</span>
  <span class="n">parse_inhibit_warnings</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">requirements</span><span class="p">)</span>
  <span class="n">parse_modular_headers</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">requirements</span><span class="p">)</span>
  <span class="n">parse_configuration_whitelist</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">requirements</span><span class="p">)</span>
  <span class="n">parse_project_name</span><span class="p">(</span><span class="nb">name</span><span class="p">,</span> <span class="n">requirements</span><span class="p">)</span>

  <span class="k">if</span> <span class="n">requirements</span> <span class="o">&amp;&amp;</span> <span class="o">!</span><span class="n">requirements</span><span class="p">.</span><span class="nf">empty?</span>
    <span class="n">pod</span> <span class="o">=</span> <span class="p">{</span> <span class="nb">name</span> <span class="o">=&gt;</span> <span class="n">requirements</span> <span class="p">}</span>
  <span class="k">else</span>
    <span class="n">pod</span> <span class="o">=</span> <span class="nb">name</span>
  <span class="k">end</span>

  <span class="n">get_hash_value</span><span class="p">(</span><span class="s1">'dependencies'</span><span class="p">,</span> <span class="p">[])</span> <span class="o">&lt;&lt;</span> <span class="n">pod</span>
  <span class="kp">nil</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">get_hash_value</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">base_value</span> <span class="o">=</span> <span class="kp">nil</span><span class="p">)</span>
  <span class="k">unless</span> <span class="no">HASH_KEYS</span><span class="p">.</span><span class="nf">include?</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
    <span class="k">raise</span> <span class="no">StandardError</span><span class="p">,</span> <span class="s2">"Unsupported hash key `</span><span class="si">#{</span><span class="n">key</span><span class="si">}</span><span class="s2">`"</span>
  <span class="k">end</span>
  <span class="n">internal_hash</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">base_value</span> <span class="k">if</span> <span class="n">internal_hash</span><span class="p">[</span><span class="n">key</span><span class="p">].</span><span class="nf">nil?</span>
  <span class="n">internal_hash</span><span class="p">[</span><span class="n">key</span><span class="p">]</span>
<span class="k">end</span>

<span class="k">def</span> <span class="nf">set_hash_value</span><span class="p">(</span><span class="n">key</span><span class="p">,</span> <span class="n">value</span><span class="p">)</span>
  <span class="k">unless</span> <span class="no">HASH_KEYS</span><span class="p">.</span><span class="nf">include?</span><span class="p">(</span><span class="n">key</span><span class="p">)</span>
    <span class="k">raise</span> <span class="no">StandardError</span><span class="p">,</span> <span class="s2">"Unsupported hash key `</span><span class="si">#{</span><span class="n">key</span><span class="si">}</span><span class="s2">`"</span>
  <span class="k">end</span>
  <span class="n">internal_hash</span><span class="p">[</span><span class="n">key</span><span class="p">]</span> <span class="o">=</span> <span class="n">value</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />经过一系列检查之后，调用 <code class="language-plaintext highlighter-rouge">get_hash_value</code> 获取 <code class="language-plaintext highlighter-rouge">internal_hash</code> 的 <code class="language-plaintext highlighter-rouge">dependencies</code>，并将 name 和 <code class="language-plaintext highlighter-rouge">requirements</code> 选项存入。<br />
<br />这里的 <code class="language-plaintext highlighter-rouge">dependencies</code> key 是定义在 TargetDefinition 文件的 <code class="language-plaintext highlighter-rouge">**HASH_KEYS**</code>，表示 Core 所支持的配置参数:<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="no">HASH_KEYS</span> <span class="o">=</span> <span class="sx">%w(
    name
    platform
    podspecs
    exclusive
    link_with
    link_with_first_target
    inhibit_warnings
    use_modular_headers
    user_project_path
    build_configurations
    project_names
    dependencies
    script_phases
    children
    configuration_pod_whitelist
    uses_frameworks
    swift_version_requirements
    inheritance
    abstract
    swift_version
)</span><span class="p">.</span><span class="nf">freeze</span>
</code></pre></div></div>

<blockquote>
  <p>Tips：freeze 表示该数组不可修改。另外，%w 用于表示其中元素被单引号括起的数组。
%W(#{foo} Bar Bar\ with\ space)
=&gt; [“Foo”, “Bar”, “Bar with space”]
对应的还有 %W 表示其中元素被双引号括起的数组。</p>
</blockquote>

<p><br />整个映射过程如下：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1599993134247-591416bf-8bbb-46cb-a8b9-86c41721acde.jpeg" alt="" /></p>

<p><a name="f7ab0349"></a></p>
<h1 id="精细化的-podfile-配置">精细化的 Podfile 配置</h1>

<p><br />最后一节让我们来展示一下 💪，看看 <code class="language-plaintext highlighter-rouge">Podfile</code> 所谓的 <code class="language-plaintext highlighter-rouge">targets</code> 之间的依赖关系可以玩出什么花来 😂。<br /></p>

<p><a name="204d60fe"></a></p>
<h2 id="target-嵌套">Target 嵌套</h2>

<p><br />最简单的 <code class="language-plaintext highlighter-rouge">Podfile</code> 就是文章开头所展示的，不过在 <code class="language-plaintext highlighter-rouge">Podfile</code> 中还可以对 Target 进行嵌套使用。假设在我们的主工程同时维护了三个项目，它们都依赖了 Alamofire，通过俄罗斯套娃就能轻松满足条件：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">target</span> <span class="s1">'Demo1'</span> <span class="k">do</span>
  <span class="n">pod</span> <span class="s1">'Alamofire'</span>

  <span class="n">target</span> <span class="s1">'Demo2'</span> <span class="k">do</span>
    <span class="n">target</span> <span class="s1">'Demo3'</span> <span class="k">do</span>
    <span class="k">end</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />编译后的 <code class="language-plaintext highlighter-rouge">Pods.project</code> 项目结构如下：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1600222941775-314f4f32-ae1d-4bb2-befc-8f46bf25c105.jpeg" alt="" /></p>

<p><br />我们知道，CocoaPods 在 <code class="language-plaintext highlighter-rouge">Pods.project</code> 中为每个在 Podfile 中声明的 Target 生成一个与之对应的专属 Target 来集成它的 Pod 依赖。对于有依赖关系的 Target 其生成的专属 Target 名称则会按照依赖关系叠加来命名，如  <code class="language-plaintext highlighter-rouge">target Demo3</code> 的专属 Target 名称为 <strong>Pods-Demo1-Demo2-Demo3</strong>。安装完成后主项目将会引入该专属 Target 来完成依赖关联，如 Demo3：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1600222941734-6b94dfeb-d608-4240-9a38-ebb812da18d0.jpeg" alt="" /></p>

<p><br />关于 Target 嵌套，一个父节点是可以有多个子节点的：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">target</span> <span class="s1">'Demo1'</span> <span class="k">do</span>
  <span class="n">pod</span> <span class="s1">'Alamofire'</span>

  <span class="n">target</span> <span class="s1">'Demo2'</span> <span class="k">do</span>
  	<span class="n">pod</span> <span class="s1">'RxSwift'</span>
  <span class="k">end</span>
  <span class="n">target</span> <span class="s1">'Demo3'</span> <span class="k">do</span>
	  <span class="n">pod</span> <span class="s1">'SwiftyJSON'</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><a name="f52857bd"></a></p>
<h2 id="abstract-target">Abstract Target</h2>

<p><br />上面例子中，由于 Demo1 与 Demo2 都需要依赖 Alamofire，我们通过 Target 嵌套让 Demo2 来继承 Demo1 的 Pods 库依赖。这么做可能会有一个限制，就是当 Demo1 的 Pod 依赖并非 Demo2 所需要的时候，就会有依赖冗余。此时就需要 <code class="language-plaintext highlighter-rouge">Abstract Target</code> 登场了。例如：<br /></p>

<div class="language-ruby highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="n">abstract_target</span> <span class="s1">'Networking'</span> <span class="k">do</span>
  <span class="n">pod</span> <span class="s1">'Alamofire'</span>

  <span class="n">target</span> <span class="s1">'Demo1'</span> <span class="k">do</span>
    <span class="n">pod</span> <span class="s1">'RxSwift'</span>
  <span class="k">end</span>
  <span class="n">target</span> <span class="s1">'Demo2'</span> <span class="k">do</span>
    <span class="n">pod</span> <span class="s1">'ReactCocoa'</span>
  <span class="k">end</span>
  <span class="n">target</span> <span class="s1">'Demo3'</span> <span class="k">do</span>
  <span class="k">end</span>
<span class="k">end</span>
</code></pre></div></div>

<p><br />将网络请求的 pod 依赖抽象到 <code class="language-plaintext highlighter-rouge">Networking</code> target 中，这样就能避免 Demo2 对 RxSwift 的依赖。这种方式配置所生成的 <code class="language-plaintext highlighter-rouge">Pods.project</code> 并不会存在名称为 <code class="language-plaintext highlighter-rouge">Networking</code> 的 Target，它仅会在主工程的专属 Target 中留下印记：<br /></p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia1600222941749-f98999d7-0a31-4523-bd31-8646c92f05fc.jpeg" alt="" /></p>

<p><a name="25f9c7fa"></a></p>
<h1 id="总结">总结</h1>

<p><br />本文结合 Xcode 工程结构来展开 CocoaPods-Core 的 Podfile 之旅，主要感受如下：<br /></p>

<ol>
  <li>再一次感受了 Ruby 语言的动态之美，给我一个字符串，还你一个未知世界；</li>
  <li>结合 Xcode 工程结构更好的理解了 Podfile 的设计初衷，<strong>基础知识很重要；</strong></li>
  <li>所谓“算法无用论”这种事情，在计算机的世界是不存在的，没有好的数据结构知识如何更好的抽象；</li>
  <li>了解 Podfile 的 DSL 是如何映射到内存中，又是如何来存储每个关键数据的</li>
</ol>

<p><a name="c6813027"></a></p>
<h1 id="知识点问题梳理">知识点问题梳理</h1>

<p><br />这里罗列了四个问题用来考察你是否已经掌握了这篇文章，如果没有建议你加入**收藏 **再次阅读：<br /></p>

<ol>
  <li>说说 TargetDefinition 的数据结构 ？</li>
  <li>说说 TargetDefinition 与 Xcode Project 的关系 ？</li>
  <li>Podfile 的文件格式有几种，分别是如何加载 ？</li>
  <li>Lockfile 和 Podfile 的关系</li>
</ol>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="CocoaPods 历险记" /><category term="Ruby" /><summary type="html"><![CDATA[引子 在上文 CocoaPods 命令解析 中，我们通过对 CLAide 的源码分析，了解了 CocoaPods 是如何处理 pod 命令，多级命令又是如何组织和嵌套的，并解释了命令行输出所代表的含义。今天我们开始学习 Podfile 。 大多 iOS 工程师最先接触到的 CocoaPods 概念应该是 Podfile，而 Podfile 属于 cocoapods-core（以下简称 Core） 的两大概念之一。另外一个则是 Podspec (用于描述 Pod Library 的配置文件)，只有当你需要开发 Pod 组件的时候才会接触。 在介绍 Podfile 的内容结构之前，必须要谈谈 Xcode 的工程结构。 Xcode 工程结构 我们先来看一个极简 Podfile 声明： target 'Demo' do pod 'Alamofire', :path =&gt; './Alamofire' end 它编译后的工程目录如下： 如你所见 Podfile 的配置是围绕 Xcode 的这些工程结构：**Workspace、Project、Target 及 Build Setting **来展开的。作为包管理工具 CocoaPods 将所管理的 Pods 依赖库组装成一个个 Target，统一放入 Pods project 中的 Demo target，并自动配置好 Target 间的依赖关系。 之后将 Example 主工程和 Pods 工程一起打包到新建的 Example.workspace，配好主工程与 Pods 工程之间的依赖，完成最终转换。 接下来，我们来聊一聊这些 Xcode 结构： Target - 最小可编译单元 A target specifies a product to build and contains the instructions for building the product from a set of files in a project or workspace. 首先是 Target，它作为工程中最小的可编译单元，根据 ****Build Phases** 和 **Build Settings** 将源码作为输入，经编译后输出结果产物**。其输出结果可以是链接库、可执行文件或者资源包等，具体细节如下： Build Setting：比如指定使用的编译器，目标平台、编译参数、头文件搜索路径等； Build 时的前置依赖、执行的脚本文件； Build 生成目标的签名、Capabilities 等属性； Input：哪些源码或者资源文件会被编译打包； Output：哪些静态库、动态库会被链接； Project - Targets 的载体 An Xcode project is a repository for all the files, resources, and information required to build one or more software products. Project 就是一个独立的 Xcode 工程，作为一个或多个 Targets 的资源管理器，本身无法被编译。Project 所管理的资源都来自它所包含的 Targets。特点如下： 至少包含一个或多个可编译的 Target； 为所包含的 Targets 定义了一份默认编译选项，如果 Target 有自己的配置，则会覆盖 Project 的预设值； 能将其他 Project 作为依赖嵌入其中； 下图为 Project 与所包含对 Targets 的关系 Workspace - 容器 A workspace is an Xcode document that groups projects 作为纯粹的项目容器，Workspace 不参与任何编译链接过程，仅用于管理同层级的 Project，其特点： Workspace 可以包含多个 Projects； 同一个 Workspace 中的 Proejct 文件对于其他 Project 是默认可见的，这些 Projcts 会共享 workspace build directory ； 一个 Xcode Project 可以被包含在多个不同的 Workspace 中，因为每个 Project 都有独立的 Identity，默认是 Project Name； Scheme - 描述 Build 过程 An Xcode scheme defines a collection of targets to build, a configuration to use when building, and a collection of tests to execute. Scheme 是对于整个 Build 过程的一个抽象，它描述了 Xcode 应该使用哪种 Build Configurations 、执行什么任务、环境参数等来构建我们所需的 Target。 Scheme 中预设了六个主要过程： Build、Run、Test、Profile、Analyze、Archive。包括了我们对 Target 的所有操作，每一个过程都可以单独配置。 CocoaPods-Core The CocoaPods-Core gem provides support to work with the models of CocoaPods, for example the Podspecs or the Podfile. CocoaPods-Core 用于 CocoaPods 中配置文件的解析，包括 Podfile、Podspec 以及解析后的依赖锁存文件，如 Podfile.lock 等。 CocoaPods-Core 的文件构成 照例，我们先通过入口文件 lib/cocoapods-core.rb 来一窥 Core 项目的主要文件： module Pod require 'cocoapods-core/gem_version' class PlainInformative &lt; StandardError; end class Informative &lt; PlainInformative; end require 'pathname' require 'cocoapods-core/vendor' # 用于存储 PodSpec 中的版本号 autoload :Version, 'cocoapods-core/version' # pod 的版本限制 autoload :Requirement, 'cocoapods-core/requirement' # 配置 Podfile 或 PodSpec 中的 pod 依赖 autoload :Dependency, 'cocoapods-core/dependency' # 获取 Github 仓库信息 autoload :GitHub, 'cocoapods-core/github' # 处理 HTTP 请求 autoload :HTTP, 'cocoapods-core/http' # 记录最终 pod 的依赖信息 autoload :Lockfile, 'cocoapods-core/lockfile' # 记录 SDK 的名称和 target 版本 autoload :Platform, 'cocoapods-core/platform' # 对应 Podfile 文件的 class autoload :Podfile, 'cocoapods-core/podfile' # 管理 PodSpec 的集合 autoload :Source, 'cocoapods-core/source' # 管理基于 CDN 来源的 PodSpec 集合 autoload :CDNSource, 'cocoapods-core/cdn_source' # 管理基于 Trunk 来源的 PodSpec 集合 autoload :TrunkSource, 'cocoapods-core/trunk_source' # 对应 PodSpec 文件的 class autoload :Specification, 'cocoapods-core/specification' # 将 pod 信息转为 .yml 文件，用于 lockfile 的序列化 autoload :YAMLHelper, 'cocoapods-core/yaml_helper' # 记录 pod 依赖类型，是静态库/动态库 autoload :BuildType, 'cocoapods-core/build_type' ... Spec = Specification end 将这些 Model 类按照对应的依赖关系进行划分，层级如下： Podfile 的主要数据结构 先来了解 Podfile 的主要数据结构 Specification The Specification provides a DSL to describe a Pod. A pod is defined as a library originating from a source. A specification can support detailed attributes for modules of code  through subspecs. Specification 即存储 PodSpec 的内容，是用于描述一个 Pod 库的源代码和资源将如何被打包编译成链接库或 framework，后续将会介绍更多的细节。 TargetDefinition The TargetDefinition stores the information of a CocoaPods static library. The target definition can be linked with one or more targets of the user project. TargetDefinition 是一个多叉树结构，每个节点记录着 Podfile 中定义的 Pod 的 Source 来源、Build Setting、Pod 子依赖等。该树的根节点指向 Podfile，而 Podfile 中的 root_target_definitions 则记录着所有的 TargetDefinition 的根节点，正常情况下该 list 中只有一个 root 即 **Pods.project**。 为了便于阅读，简化了大量的 DSL 配置相关的方法和属性并对代码顺序做了调整，大致结构如下： module Pod class Podfile class TargetDefinition # 父节点: TargetDefinition 或者 Podfile attr_reader :parent # 子节点: TargetDefinition attr_reader :children # 记录 tareget 的配置信息 attr_accessor :internal_hash def root? parent.is_a?(Podfile) || parent.nil? end def root if root? self else parent.root end end def podfile root.parent end # ... end end 对应上一节 Xcode 工程结构中的 Podfile 关系如下： CocoaPods 正是巧妙利用了 Xcode 工程结构的特点，引入  Pods.project 这一中间层，将主工程的 Pods 依赖全部转接到 Pods.project 上，最后再将 Pods.project 作为主项目的依赖。尽管这么做也受到了一些质疑和诟病（所谓的侵入性太强），但笔者的观点是，正得益于 Pods.project 这一设计隔绝了第三方依赖库对于主项目的频繁更改，也便于后续的管理和更新，体现了软件工程中的开放-关闭原则。 比如，在 Pod 1.7.0 版本中支持的 Multiple Xcodeproj Generation 就是解决随着项目的迭代而日益增大的 Pods project 的问题。试想当你的项目中存在上百个依赖库，每个依赖库的变更都会影响到你的主工程，这将是非常可怕的问题。 Podfile The Podfile is a specification that describes the dependencies of the targets of one or more Xcode projects. Podfile 是用于描述一个或多个 Xcode Project 中各个 Targets 之间的依赖关系。 这些 Targets 的依赖关系对应的就是 TargetDefinition 树中的各子节点的层级关系。如前面所说，有了 Podfile 这个根节点的指向，仅需对依赖树进行遍历，就能轻松获取完整的依赖关系。 有了这层依赖树，对于某个 Pod 库的更新即是对树节点的更新，便可轻松的分析出此次更新涉及的影响。 简化调整后的 Podfile 代码如下： require 'cocoapods-core/podfile/dsl' require 'cocoapods-core/podfile/target_definition' module Pod class Podfile include Pod::Podfile::DSL # podfile 路径 attr_accessor :defined_in_file # 所有的 TargetDefinition 的根节点, 正常只有一个，即 Pods.project target attr_accessor :root_target_definitions # 记录 Pods.project 项目的配置信息 attr_accessor :internal_hash # 当前 DSL 解析使用的 TargetDefinition attr_accessor :current_target_definition # ... end end 直接看 dsl.rb，该文件内部定义了 Podfile DSL 支持的所有方法。通过 include 的使用将 Pod::Podfile::DSL 模块 Mix-in 后插入到 Podfile 类中。想了解更多 Mix-in 特性，移步 Ruby 特性之 Mix-in。 Lockfile The Lockfile stores information about the pods that were installed by  CocoaPods. Lockfile，顾名思义是用于记录最后一次 CocoaPods 所安装的 Pod 依赖库版本的信息快照。也就是生成的 **Podfile.lock。** 在 pod install 过程，Podfile 会结合它来确认最终所安装的 Pod 版本，固定 Pod 依赖库版本防止其自动更新。Lockfile 也作为 Pods 状态清单 (mainfest)，用于记录安装过程的中哪些 Pod 需要被删除或安装或更新等。 以开头的 Podfile 经 pod install 所生成的 Podfile.lock 为例： PODS: - Alamofire (4.6.0) DEPENDENCIES: - Alamofire (from `./Alamofire`) EXTERNAL SOURCES: Alamofire: :path: "./Alamofire" SPEC CHECKSUMS: Alamofire: 0dda98a0ed7eec4bdcd5fe3cdd35fcd2b3022825 PODFILE CHECKSUM: da12cc12a30cfb48ebc5d14e8f51737ab65e8241 COCOAPODS: 1.10.0.beta.2 我们来分析一下，通过该 Lockfile 能够获取哪些信息： Key 含义 PODS 记录所有 Pod 库的具体安装版本号 DEPENDENCIES 记录各 Pod 库之间的相互依赖关系，由于这里只有 Alamofire 且它无其他依赖，暂时无关看出区别 EXTERNAL SOURCES 记录部分通过外部源的 Pod 库（Git 引入、Path 引入） SPEC CHECKSUMS 记录当前各 Pod 库的 Podspec 文件 Hash 值，其实就是文件的 md5 PODFILE CHECKSUM 记录 Podfile 文件的 Hash 值，同样是 md5，确认是否有变更 COCOAPODS 记录上次所使用的 CocoaPods 版本 Podfile 内容加载 Podfile 文件类型 你可以在 CocoaPods 的 /lib/cocoapods/config.rb 找到 Podfile 所支持的文件类型： PODFILE_NAMES = [ 'CocoaPods.podfile.yaml', 'CocoaPods.podfile', 'Podfile', 'Podfile.rb', ].freeze CocoaPods 按照上述命名优先级来查找工程目录下所对应的 Podfile 文件。当发现目录中存在 CocoaPods.podfile.yaml 文件时会优先加载。很多同学可能只知道到 Podfile 支持 Ruby 的文件格式，而不了解它还支持了 YAML 格式。YAML 是 YAML Ain't Markup Language 的缩写，其 官方定义： YAML is a human friendly data serialization standard for all programming languages. 它是一种面向工程师友好的序列化语言。我们的 Lockfile 文件就是以 YAML 格式写入 Podfile.lock 中的。 Podfile 文件读取 回到 lib/cocoapods-core/podfile.rb 来看读取方法： module Pod class Podfile include Pod::Podfile::DSL def self.from_file(path) path = Pathname.new(path) unless path.exist? raise Informative, "No Podfile exists at path `#{path}`." end # 这里我们可以看出，Podfile 目前已经支持了结尾是 .podfile 和 .rb 后缀的文件名 # 其实是为了改善很多编译器使用文件后缀来确认 filetype，比如 vim # 相比与 Podfile 这个文件名要更加的友好 case path.extname when '', '.podfile', '.rb' Podfile.from_ruby(path) when '.yaml' # 现在也支持了 .yaml 格式 Podfile.from_yaml(path) else raise Informative, "Unsupported Podfile format `#{path}`." end end end from_file 在 pod install 命令执行后的 verify_podfile_exists! 中被调用的： def verify_podfile_exists! unless config.podfile raise Informative, "No `Podfile' found in the project directory." end end 而 Podfile 文件的读取就是 config.podfile  里触发的，代码在 CocoaPods 的 config.rb 文件中： def podfile_path_in_dir(dir) PODFILE_NAMES.each do |filename| candidate = dir + filename if candidate.file? return candidate end end nil end def podfile_path @podfile_path ||= podfile_path_in_dir(installation_root) end def podfile @podfile ||= Podfile.from_file(podfile_path) if podfile_path end 这里的方法 podfile 和 podfile_path 都是 lazy 加载的。最后 Core 的 from_file 将依据目录下的 Podfile 文件类型选择调用 from_yaml 或者 from_ruby。 从 Pod::Command::Install 命令到 Podfile 文件加载的调用栈如下： Podfile From Ruby 解析 当我们通过 pod init 来初始化 CocoaPods 项目时，默认生成的 Podfile 名称就是 Podfile，那就从 Podfile.from_ruby 开始。 def self.from_ruby(path, contents = nil) # ① contents ||= File.open(path, 'r:utf-8', &amp;:read) # 兼容 1.9 版本的 Rubinius 中的编码问题 if contents.respond_to?(:encoding) &amp;&amp; contents.encoding.name != 'UTF-8' contents.encode!('UTF-8') end # 对 Podfile 中不规范的单引号或双引号进行检查，并进行自动修正，及抛出错误 if contents.tr!('“”‘’‛', %(""''')) CoreUI.warn "..." end # ② podfile = Podfile.new(path) do begin eval(contents, nil, path.to_s) rescue Exception =&gt; e message = "Invalid `#{path.basename}` file: #{e.message}" raise DSLError.new(message, path, e, contents) end end podfile end ① 是对 Podfile 内容的读取和编码，同时对可能出现的单引号和双引号的匹配问题进行了修正。② 以 path 和 block 为入参进行 podfile 类的初始化并将其放回，保存在全局的 config.podfile 中。 Tips: 如果要在 Ruby 对象的初始化中传入参数，需要重载 Object 的 initialize 方法，这里的 Podfile.new(…) 本质上是 initialize 的方法调用。 initialize 方法所传入的尾随闭包 block 的核心在于内部的 eval 函数（在 CocoaPods 核心组件 中有提到）： eval(contents, nil, path.to_s) 它将 Podfile 中的文本内容转化为方法执行，也就是说里面的参数是一段 Ruby 的代码字符串，通过 eval 方法可以直接执行。继续看 Podfile 的 initialize 方法： def initialize(defined_in_file = nil, internal_hash = {}, &amp;block) self.defined_in_file = defined_in_file @internal_hash = internal_hash if block default_target_def = TargetDefinition.new('Pods', self) default_target_def.abstract = true @root_target_definitions = [default_target_def] @current_target_definition = default_target_def instance_eval(&amp;block) else @root_target_definitions = [] end end 它定义了三个参数： 参数 定义 defined_in_file Podfile 文件路径 internal_hash 通过 yaml 序列化得到的 Podfile 配置信息，保存在 internal_hash 中 block 用于映射 Podfile 的 DSL 配置 需要注意的是，通过 from_ruby 初始化的 Podfile 只传入了参数 1 和 3，参数 2 internal_hash 则是提供给 from_yaml 的。 当 block 存在，会初始化名为 Pods 的 TargetDefinition 对象，用于保存 Pods project 的相关信息和 Pod 依赖。然后调用 instance_eval 执行传入的 block，将 Podfile 的 DSL 内容转换成对应的方法和参数，最终将参数存入 internal_hash 和对应的 target_definitions 中。 Tips: 在 Ruby 中存在两种不同的方式来执行代码块 block，分别是 instance_eval 和 class_eval。 class_eval 的执行上下文与调用类相关，调用者是类名或者模块名，而 instance_eval 的调用者可以是类的实例或者类本身。细节看 StackoverFlow。 Podfile From YAML 解析 YAML 格式的 Podfile 加载需要借助 YAMLHelper 类来完成，YAMLHelper 则是基于 yaml 的简单封装。 def self.from_yaml(path) string = File.open(path, 'r:utf-8', &amp;:read) # 为了解决 Rubinius incomplete encoding in 1.9 mode # https://github.com/rubinius/rubinius/issues/1539 if string.respond_to?(:encoding) &amp;&amp; string.encoding.name != 'UTF-8' string.encode!('UTF-8') end hash = YAMLHelper.load_string(string) from_hash(hash, path) end def self.from_hash(hash, path = nil) internal_hash = hash.dup target_definitions = internal_hash.delete('target_definitions') || [] podfile = Podfile.new(path, internal_hash) target_definitions.each do |definition_hash| definition = TargetDefinition.from_hash(definition_hash, podfile) podfile.root_target_definitions &lt;&lt; definition end podfile end 通过 from_yaml 将文件内容转成 Ruby hash 后转入 from_hash 方法。 区别于 from_ruby，这里调用的 initialize 将读取的 hash 直接存入 internal_hash，然后利用 TargetDefinition.from_hash 来完成的 hash 内容到 targets 的转换，因此，这里无需传入 block 进行 DSL 解析和方法转换。 Podfile 内容解析 前面提到 Podfile 的内容最终保存在 internal_hash 和 target_definitions 中，本质上都是使用了 hash 来保存数据。由于 YAML 文件格式的 Podfile 加载后就是 hash 对象，无需过多加工。唯一需要处理的是递归调用 TargetDefinition 的 from_hash 方法来解析 target 子节点的数据。 因此，接下来的内容解析主要针对 Ruby 文件格式的 DSL 解析，我们以 pod 方法为例： target 'Example' do pod 'Alamofire' end 当解析到 pod 'Alamofire' 时，会先通过 eval(contents, nil, path.to_s 将其转换为 dsl.rb 中的方法： def pod(name = nil, *requirements) unless name raise StandardError, 'A dependency requires a name.' end current_target_definition.store_pod(name, *requirements) end name 为 Alamofire，由于我们没有指定对应的 Alamofire 版本，默认会使用最新版本。requirements  是控制 该 pod 来源获取或者 pod target 的编译选项等，例如： pod 'Alamofire', '0.9' pod 'Alamofire', :modular_headers =&gt; true pod 'Alamofire', :configurations =&gt; ['Debug', 'Beta'] pod 'Alamofire', :source =&gt; 'https://github.com/CocoaPods/Specs.git' pod 'Alamofire', :subspecs =&gt; ['Attribute', 'QuerySet'] pod 'Alamofire', :testspecs =&gt; ['UnitTests', 'SomeOtherTests'] pod 'Alamofire', :path =&gt; '~/Documents/AFNetworking' pod 'Alamofire', :podspec =&gt; 'https://example.com/Alamofire.podspec' pod 'Alamofire', :git =&gt; 'https://github.com/looseyi/Alamofire.git', :tag =&gt; '0.7.0' Tips：requirements 最终是以 Gem::Requirement 对象来保存的。关于 pod 详细说明请移步：Podfile 手册。 对 name 进行校验后，直接转入 current_target_definition 毕竟 Pod 库都是存在 Pods.project 之下： def store_pod(name, *requirements) return if parse_subspecs(name, requirements) # This parse method must be called first parse_inhibit_warnings(name, requirements) parse_modular_headers(name, requirements) parse_configuration_whitelist(name, requirements) parse_project_name(name, requirements) if requirements &amp;&amp; !requirements.empty? pod = { name =&gt; requirements } else pod = name end get_hash_value('dependencies', []) &lt;&lt; pod nil end def get_hash_value(key, base_value = nil) unless HASH_KEYS.include?(key) raise StandardError, "Unsupported hash key `#{key}`" end internal_hash[key] = base_value if internal_hash[key].nil? internal_hash[key] end def set_hash_value(key, value) unless HASH_KEYS.include?(key) raise StandardError, "Unsupported hash key `#{key}`" end internal_hash[key] = value end 经过一系列检查之后，调用 get_hash_value 获取 internal_hash 的 dependencies，并将 name 和 requirements 选项存入。 这里的 dependencies key 是定义在 TargetDefinition 文件的 **HASH_KEYS**，表示 Core 所支持的配置参数: HASH_KEYS = %w( name platform podspecs exclusive link_with link_with_first_target inhibit_warnings use_modular_headers user_project_path build_configurations project_names dependencies script_phases children configuration_pod_whitelist uses_frameworks swift_version_requirements inheritance abstract swift_version ).freeze Tips：freeze 表示该数组不可修改。另外，%w 用于表示其中元素被单引号括起的数组。 %W(#{foo} Bar Bar\ with\ space) =&gt; [“Foo”, “Bar”, “Bar with space”] 对应的还有 %W 表示其中元素被双引号括起的数组。 整个映射过程如下： 精细化的 Podfile 配置 最后一节让我们来展示一下 💪，看看 Podfile 所谓的 targets 之间的依赖关系可以玩出什么花来 😂。 Target 嵌套 最简单的 Podfile 就是文章开头所展示的，不过在 Podfile 中还可以对 Target 进行嵌套使用。假设在我们的主工程同时维护了三个项目，它们都依赖了 Alamofire，通过俄罗斯套娃就能轻松满足条件： target 'Demo1' do pod 'Alamofire' target 'Demo2' do target 'Demo3' do end end end 编译后的 Pods.project 项目结构如下： 我们知道，CocoaPods 在 Pods.project 中为每个在 Podfile 中声明的 Target 生成一个与之对应的专属 Target 来集成它的 Pod 依赖。对于有依赖关系的 Target 其生成的专属 Target 名称则会按照依赖关系叠加来命名，如  target Demo3 的专属 Target 名称为 Pods-Demo1-Demo2-Demo3。安装完成后主项目将会引入该专属 Target 来完成依赖关联，如 Demo3： 关于 Target 嵌套，一个父节点是可以有多个子节点的： target 'Demo1' do pod 'Alamofire' target 'Demo2' do pod 'RxSwift' end target 'Demo3' do pod 'SwiftyJSON' end end Abstract Target 上面例子中，由于 Demo1 与 Demo2 都需要依赖 Alamofire，我们通过 Target 嵌套让 Demo2 来继承 Demo1 的 Pods 库依赖。这么做可能会有一个限制，就是当 Demo1 的 Pod 依赖并非 Demo2 所需要的时候，就会有依赖冗余。此时就需要 Abstract Target 登场了。例如： abstract_target 'Networking' do pod 'Alamofire' target 'Demo1' do pod 'RxSwift' end target 'Demo2' do pod 'ReactCocoa' end target 'Demo3' do end end 将网络请求的 pod 依赖抽象到 Networking target 中，这样就能避免 Demo2 对 RxSwift 的依赖。这种方式配置所生成的 Pods.project 并不会存在名称为 Networking 的 Target，它仅会在主工程的专属 Target 中留下印记： 总结 本文结合 Xcode 工程结构来展开 CocoaPods-Core 的 Podfile 之旅，主要感受如下： 再一次感受了 Ruby 语言的动态之美，给我一个字符串，还你一个未知世界； 结合 Xcode 工程结构更好的理解了 Podfile 的设计初衷，基础知识很重要； 所谓“算法无用论”这种事情，在计算机的世界是不存在的，没有好的数据结构知识如何更好的抽象； 了解 Podfile 的 DSL 是如何映射到内存中，又是如何来存储每个关键数据的 知识点问题梳理 这里罗列了四个问题用来考察你是否已经掌握了这篇文章，如果没有建议你加入**收藏 **再次阅读： 说说 TargetDefinition 的数据结构 ？ 说说 TargetDefinition 与 Xcode Project 的关系 ？ Podfile 的文件格式有几种，分别是如何加载 ？ Lockfile 和 Podfile 的关系]]></summary></entry><entry><title type="html">公积金贷买房能省多少钱</title><link href="https://www.desgard.com/2020/09/14/buy-big-house-in-sh-1.html" rel="alternate" type="text/html" title="公积金贷买房能省多少钱" /><published>2020-09-14T00:00:00-08:00</published><updated>2020-09-14T00:00:00-08:00</updated><id>https://www.desgard.com/2020/09/14/buy-big-house-in-sh-1</id><content type="html" xml:base="https://www.desgard.com/2020/09/14/buy-big-house-in-sh-1.html"><![CDATA[<blockquote>
  <p>我给自己定了一个将近 700 天的计划，这就是在上海买房定居。于是开启了研究购房政策、研究小区和板块、研究购房注意事项等一系列的调研和研究。我将这些笔记归档成文章，发表在公众号与大家分享。</p>
</blockquote>

<p><strong>今天距离购房还有 675 天。</strong></p>

<p>这篇文章来讨论使用公积金贷款买房的最大化省钱空间。<strong>以下讨论均针对于上海市</strong>。因为公积金贷款比商业贷款利率低了近两个点，所以公积金贷款也是购房者的首选。下面我来较为全面的记录一下公积金贷款的所有细节问题。</p>

<h1 id="使用公积金贷款的条件">使用公积金贷款的条件</h1>

<ol>
  <li>购买上海市具有所有权的自住住房；</li>
  <li>申请贷款前 6 个月连续正常缴存住房公积金；</li>
  <li>借款人家庭没有尚未还清的公积金债务；</li>
</ol>

<h1 id="利率数据">利率数据</h1>

<p>首先先给出公积金贷款的贷款利率（以下表内加粗为一般大家所需要关注的数据）：</p>

<table>
  <thead>
    <tr>
      <th style="text-align: left">贷款年限</th>
      <th style="text-align: left">首套房、二套房普通住宅（基准利率 - 2015.4.8 起开始执行）</th>
      <th style="text-align: left">二套房非普通住宅（1.1 倍利率）</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">五年以下（包含五年）</td>
      <td style="text-align: left">2.75%</td>
      <td style="text-align: left">3.025%</td>
    </tr>
    <tr>
      <td style="text-align: left">五年以上</td>
      <td style="text-align: left"><strong>3.25%</strong></td>
      <td style="text-align: left">3.575%</td>
    </tr>
  </tbody>
</table>

<h1 id="最高贷款额度">最高贷款额度</h1>

<p>这里不讨论非普通住宅。</p>

<ul>
  <li>普通住宅：按所在地一般民用住宅建筑标准来建造的作为居住用途的房屋，目前多为多层住宅与高层住宅。</li>
  <li>非普通住宅：非普通住宅一般指宅建筑面积较大或用作商业用途的房子。</li>
</ul>

<table>
  <thead>
    <tr>
      <th style="text-align: left">所购住房</th>
      <th style="text-align: left">首套房</th>
      <th style="text-align: left">首套房</th>
      <th style="text-align: left">二套房普通</th>
      <th style="text-align: left">二套房普通</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">贷款家庭</td>
      <td style="text-align: left">1 人贷款</td>
      <td style="text-align: left"><strong>≥ 2 人贷款</strong></td>
      <td style="text-align: left">1 人贷款</td>
      <td style="text-align: left">≥ 2 人贷款</td>
    </tr>
    <tr>
      <td style="text-align: left">缴纳住房公积金最高可贷金额</td>
      <td style="text-align: left">50 万</td>
      <td style="text-align: left"><strong>100 万</strong></td>
      <td style="text-align: left">50 万</td>
      <td style="text-align: left">100 万</td>
    </tr>
    <tr>
      <td style="text-align: left">缴纳补充公积金最高可贷金额</td>
      <td style="text-align: left">10 万</td>
      <td style="text-align: left"><strong>20 万</strong></td>
      <td style="text-align: left">10 万</td>
      <td style="text-align: left">20 万</td>
    </tr>
    <tr>
      <td style="text-align: left">可贷金额总计</td>
      <td style="text-align: left">60 万</td>
      <td style="text-align: left"><strong>120 万</strong></td>
      <td style="text-align: left">60 万</td>
      <td style="text-align: left">120 万</td>
    </tr>
    <tr>
      <td style="text-align: left">首付比列</td>
      <td style="text-align: left"><strong>≤ 90 平米，不低于 20%; ＞ 90 平米不低于 30%</strong></td>
      <td style="text-align: left">同左</td>
      <td style="text-align: left">不低于 30\%</td>
      <td style="text-align: left">同左</td>
    </tr>
  </tbody>
</table>

<p>这里面我们可以发现住房公积金和补充公积金是有个上限值，但是如何出自己的可贷公积金的数值呢？其实是有如下计算公式：假如我们另当前住房公积金账户余额是，补充公积金账户余额是，则最高可贷金额有如下关系：</p>

\[\begin{cases}
f(x, y)=40x+20y \\
40x \leq 50 \times 10^{4} \\ 
20y \leq 10 \times 10^{4} 
\end{cases}\]

<p>通俗的翻译过来就是，<strong>公积金最高可贷金额 = 住房公积金余额 × 40 + 补充公积金余额 × 20</strong>。所以通过不等式反解我们可得，<strong>如果我们想最大的利用公积金，那么我们住房公积金最少需要有 12500 元的余额、补充公积金需要有 5000 块钱的余额，就满足了最高可贷金额的条件。</strong></p>

<h1 id="贷款年限和贷款人年龄限制">贷款年限和贷款人年龄限制</h1>

<p>首先，如果是新建商品房，也就是房龄为 0 年的房子，最长贷款年限是 30 年。然后我们说二手房，它有以下规则：</p>

<table>
  <thead>
    <tr>
      <th style="text-align: left">房龄</th>
      <th style="text-align: left">最长贷款年限</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td style="text-align: left">≤ 5 年</td>
      <td style="text-align: left">30 年</td>
    </tr>
    <tr>
      <td style="text-align: left">6 - 19 年</td>
      <td style="text-align: left"><strong>35 年 - 房龄（假如是 10 年房龄，则最高可贷 25 年）</strong></td>
    </tr>
    <tr>
      <td style="text-align: left">≥ 20 年</td>
      <td style="text-align: left">15 年</td>
    </tr>
  </tbody>
</table>

<h1 id="贷款算法">贷款算法</h1>

<p>同商业贷款的算法相同，公积金贷款也分成等额本金和等额本息两种算法。考虑到更多的人愿意均摊风险以及银行希望获取到更高的利息收入，所以这里我均采用<strong>等额本息来计算还款总额</strong>。</p>

<h2 id="每月月供">每月月供</h2>

\[月供额 = \frac{月利率 \times (1+月利率)^{还款月数}}{(1+月利率)^{还款月数} - 1} \times 贷款本金\]

<p>其中月利率的计算方法：</p>

\[月利率 = \frac{年利率}{12}\]

<h2 id="其他约束">其他约束</h2>

<p>除了我们上文提到的公积金余额对于贷款的约束，我们还要考虑房龄所带来的影响：</p>

\[还款月数 = (35 - 房龄) \times 12\]

<h2 id="举例计算">举例计算</h2>

<p>以上就是我们要考虑的所有月数条件，那么我们来举一个例子来进行计算。假如我们现在要买一个 2010 年（房龄 10 年的二手房），总价是 400 万。使用了 35\% 的首付比例之后，我们需要<strong>贷款 260 万</strong>，最长贷款时间 25 年，也就是<strong>还款月数 300 个月</strong>。</p>

<h3 id="情况一全部使用商业贷款">情况一：全部使用商业贷款</h3>

<p>先要确定一下商业贷款的利息，我这里查阅了一下资料，由于上海的商贷金额往往较高，银行会对利息进行 95 折的优惠，从 4.9\% 的基准利率下调到 4.655\%。但今年国家出了 LPR 的利息策略，<strong>我们用当前 8 月份的 LPR 利息 4.65\% 来计算</strong>。首先来算月利率：</p>

\[月利率 = \frac{4.65\%}{12} = 0.003875\]

<p>然后我们来带入计算月供：</p>

\[\begin{split}
月供额 &amp;= \frac {0.003875 \times (1 + 0.003875)^{300}}{(1 + 0.003875)^{300} - 1} \times 2.6 \times 10^6 \\
&amp;\approx 14673.899\ 元 
\end{split}\]

\[\begin{equation}
\begin{split}
月供额 &amp;= \frac {0.003875 \times (1 + 0.003875)^{300}}{(1 + 0.003875)^{300} - 1} \times 2.6 \times 10^6 \\
&amp;\approx 14673.899\ 元 
\end{split}
\end{equation}\]

<p>使用月供额来乘以 30 个月算出总还款：</p>

\[总还款 = 30 * 14673.899 = 4402169.7\ 元\]

<h3 id="情况二使用最大组合贷">情况二：使用最大组合贷</h3>

<p>由于<strong>公积金贷款只能贷 120 万，所以采用 120 万是公积金贷，利息是五年以上的 3.75\%。我们用当前 8 月份的 LPR 利息 4.65\% 当做商业贷款的利息，商业贷款 140 万</strong>。</p>

<p>同上述计算法相同，带入公式。</p>

<p><strong>① 公积金贷款</strong></p>

<p>公积金贷款的月供：</p>

\[公积金月供 \approx 6169.57 元\]

<p>300 个月公积金总还款：</p>

\[公积金总还款 = 1850871 \ 元\]

<p><strong>② 商业贷款</strong></p>

<p>商业贷款月供：</p>

\[商业贷款月供 \approx 7901.33\ 元\]

<p>300 个月商贷总还款：</p>

\[商贷总还款 = 2370399元\]

<p>我们得到总还款数：</p>

\[总还款 = 1850871 + 2370399 = 4221270 元\]

<h3 id="结果分析">结果分析</h3>

<p>从上面的计算结果来看，我们购买房龄为 10 年的二手房，加入总价为 400 万元，则选择组合贷<strong>可以节省 180900 元</strong>。</p>

<h1 id="数据分析">数据分析</h1>

<p>上面已经给出了等额本息的计算方法。所以接下来进行控制变量，<strong>我们让贷款年限映射到正实数区间，让其投影在 5 年与 30 年之间</strong>。保证贷款金额为 400 万。然后我们来计算纯商贷和使用组合贷的数据。蓝色线代表使用纯商贷模式，红色线代表使用组合贷模式。</p>

<p><img src="https://raw.githubusercontent.com/Desgard/img/master/img/guardia640" alt="" /></p>

<p>由图一可以看出，<strong>还款年份数越多，其所需还款金额越多，也就意味着利息越高</strong>。而红（组合贷）与蓝（纯商贷）的差距也越来越大。<strong>并且由右图可知，当还款年份数越多，组合贷的优势愈加明显</strong>。</p>

<h1 id="总结">总结</h1>

<p>接下来我们来总结一下买房贷款的最大化利益策略：</p>

<ol>
  <li>所以贷款买房尽量可以使用公积金贷款。可贷最大公积金额度需要我们以及我们的配偶具有<strong>住房公积金余额 12500 元、补充公积金余额 5000 元。</strong></li>
  <li>根据<strong>最大贷款额原则</strong>（之后会讲到，结论是“首套房付最少的首付，用最大的杠杆贷最多的款，选择 30 年等额本息法，拒不提前还款”策略可达最大收益），<strong>当我们将还款时间设置为 30 年的上限阈值，在公积金贷款中也可以获得最大化的成本节约</strong>。当然，这就要求我们购买新房和房龄小的二手房。</li>
</ol>

<p>如果你有任何问题以及更好的建议，<strong>可以在下方评论区留言</strong>。</p>

<h1 id="相关数据分析代码">相关数据分析代码</h1>

<p>以下代码由我个人编写，可在 Jupyter Notebook 环境下直接运行。</p>

<div class="language-python highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="s">"""等额本息算法描述"""</span>

<span class="kn">import</span> <span class="nn">numpy</span> <span class="k">as</span> <span class="n">np</span>
<span class="kn">import</span> <span class="nn">math</span>

<span class="c1"># 等额本息算法
</span><span class="k">def</span> <span class="nf">averageCapitalPlusInterest</span><span class="p">(</span><span class="n">principal</span><span class="p">,</span> <span class="n">anualInterestRate</span><span class="p">,</span> <span class="n">month</span><span class="p">):</span>
    <span class="s">"""
    principal 表示贷款总额, anualInterestRate 表示年利率, month 表示房贷月份
    """</span>
    <span class="c1"># 计算每月应还款金额
</span>    <span class="n">monthlyPayment</span> <span class="o">=</span> <span class="n">np</span><span class="p">.</span><span class="n">around</span><span class="p">(</span><span class="n">principal</span> <span class="o">*</span> <span class="n">averageCapitalPlusInterestRate</span><span class="p">(</span><span class="n">month</span><span class="p">,</span> <span class="n">monthlyInterestRate</span><span class="p">(</span><span class="n">anualInterestRate</span><span class="p">)),</span> <span class="mi">2</span><span class="p">)</span>
    <span class="c1"># 还款总额
</span>    <span class="n">totalPayment</span> <span class="o">=</span> <span class="n">np</span><span class="p">.</span><span class="n">around</span><span class="p">(</span><span class="n">monthlyPayment</span> <span class="o">*</span> <span class="n">month</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">totalPayment</span>

<span class="c1"># 计算每月利率
</span><span class="k">def</span> <span class="nf">monthlyInterestRate</span><span class="p">(</span><span class="n">anualInterestRate</span><span class="p">):</span>
    <span class="n">s</span> <span class="o">=</span> <span class="n">anualInterestRate</span> <span class="o">/</span> <span class="mi">12</span>
    <span class="k">return</span> <span class="n">s</span>

<span class="c1"># 计算比例系数
</span><span class="k">def</span> <span class="nf">averageCapitalPlusInterestRate</span><span class="p">(</span><span class="n">month</span><span class="p">,</span> <span class="n">monthlyInterestRate</span><span class="p">):</span>
    <span class="n">R</span> <span class="o">=</span> <span class="n">monthlyInterestRate</span>
    <span class="n">N</span> <span class="o">=</span> <span class="n">month</span>
    <span class="n">I</span> <span class="o">=</span> <span class="n">R</span> <span class="o">*</span> <span class="n">math</span><span class="p">.</span><span class="nb">pow</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="n">R</span><span class="p">,</span> <span class="n">N</span><span class="p">)</span> <span class="o">/</span> <span class="p">(</span><span class="n">math</span><span class="p">.</span><span class="nb">pow</span><span class="p">(</span><span class="mi">1</span> <span class="o">+</span> <span class="n">R</span><span class="p">,</span> <span class="n">N</span><span class="p">)</span> <span class="o">-</span> <span class="mi">1</span><span class="p">)</span>
    <span class="k">return</span> <span class="n">I</span>

<span class="s">"""贷款数据模拟"""</span>
<span class="c1"># 全商贷
</span><span class="n">r</span> <span class="o">=</span> <span class="mf">0.0465</span>
<span class="n">ms</span> <span class="o">=</span> <span class="p">[</span><span class="mi">12</span> <span class="o">*</span> <span class="n">mi</span> <span class="k">for</span> <span class="n">mi</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="mi">6</span><span class="p">,</span> <span class="mi">31</span><span class="p">)]</span>
<span class="n">t</span> <span class="o">=</span> <span class="mi">4000000</span>
<span class="n">res</span> <span class="o">=</span> <span class="p">[]</span>

<span class="k">for</span> <span class="n">m</span> <span class="ow">in</span> <span class="n">ms</span><span class="p">:</span>
    <span class="n">res</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">averageCapitalPlusInterest</span><span class="p">(</span><span class="n">t</span><span class="p">,</span> <span class="n">r</span><span class="p">,</span> <span class="n">m</span><span class="p">))</span>
<span class="n">res</span> <span class="o">=</span> <span class="p">[</span><span class="n">np</span><span class="p">.</span><span class="n">around</span><span class="p">(</span><span class="n">x</span> <span class="o">/</span> <span class="mi">10000</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">res</span><span class="p">]</span>

<span class="c1"># 组合贷
</span>
<span class="n">r1</span> <span class="o">=</span> <span class="mf">0.0465</span>
<span class="n">r2</span> <span class="o">=</span> <span class="mf">0.0375</span>
<span class="n">t2</span> <span class="o">=</span> <span class="mi">1200000</span>
<span class="n">t1</span> <span class="o">=</span> <span class="n">t</span> <span class="o">-</span> <span class="n">t2</span>

<span class="n">rest</span> <span class="o">=</span> <span class="p">[]</span>

<span class="k">for</span> <span class="n">m</span> <span class="ow">in</span> <span class="n">ms</span><span class="p">:</span>
    <span class="n">rest</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">averageCapitalPlusInterest</span><span class="p">(</span><span class="n">t1</span><span class="p">,</span> <span class="n">r1</span><span class="p">,</span> <span class="n">m</span><span class="p">)</span> <span class="o">+</span> <span class="n">averageCapitalPlusInterest</span><span class="p">(</span><span class="n">t2</span><span class="p">,</span> <span class="n">r2</span><span class="p">,</span> <span class="n">m</span><span class="p">))</span>
<span class="n">rest</span> <span class="o">=</span> <span class="p">[</span><span class="n">np</span><span class="p">.</span><span class="n">around</span><span class="p">(</span><span class="n">x</span> <span class="o">/</span> <span class="mi">10000</span><span class="p">,</span> <span class="mi">2</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">rest</span><span class="p">]</span>

<span class="s">"""做图"""</span>

<span class="kn">import</span> <span class="nn">matplotlib.pyplot</span> <span class="k">as</span> <span class="n">plt</span>

<span class="n">year</span> <span class="o">=</span> <span class="p">[</span><span class="n">m</span> <span class="o">//</span> <span class="mi">12</span> <span class="k">for</span> <span class="n">m</span> <span class="ow">in</span> <span class="n">ms</span><span class="p">]</span>

<span class="n">plt</span><span class="p">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">221</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">plot</span><span class="p">(</span><span class="n">year</span><span class="p">,</span> <span class="n">res</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">plot</span><span class="p">(</span><span class="n">year</span><span class="p">,</span> <span class="n">rest</span><span class="p">,</span> <span class="s">'r'</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">xlabel</span><span class="p">(</span><span class="s">"Loan Time - Year"</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">ylabel</span><span class="p">(</span><span class="s">"Repayment Amount - RMB"</span><span class="p">)</span>

<span class="n">plt</span><span class="p">.</span><span class="n">subplot</span><span class="p">(</span><span class="mi">222</span><span class="p">)</span>
<span class="n">detal</span> <span class="o">=</span> <span class="p">[]</span>
<span class="k">for</span> <span class="n">i</span> <span class="ow">in</span> <span class="nb">range</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">res</span><span class="p">)):</span>
    <span class="n">detal</span><span class="p">.</span><span class="n">append</span><span class="p">(</span><span class="n">res</span><span class="p">[</span><span class="n">i</span><span class="p">]</span> <span class="o">-</span> <span class="n">rest</span><span class="p">[</span><span class="n">i</span><span class="p">])</span>

<span class="n">rects</span> <span class="o">=</span> <span class="n">plt</span><span class="p">.</span><span class="n">bar</span><span class="p">(</span><span class="n">year</span><span class="p">,</span> <span class="n">detal</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">xlabel</span><span class="p">(</span><span class="s">"Loan Time - Year"</span><span class="p">)</span>
<span class="n">plt</span><span class="p">.</span><span class="n">ylabel</span><span class="p">(</span><span class="s">"Savings - RMB"</span><span class="p">)</span>

<span class="k">for</span> <span class="n">rect</span> <span class="ow">in</span> <span class="n">rects</span><span class="p">:</span>
    <span class="n">height</span> <span class="o">=</span> <span class="n">np</span><span class="p">.</span><span class="n">around</span><span class="p">(</span><span class="n">rect</span><span class="p">.</span><span class="n">get_height</span><span class="p">(),</span> <span class="mi">1</span><span class="p">)</span>
    <span class="n">plt</span><span class="p">.</span><span class="n">text</span><span class="p">(</span><span class="n">rect</span><span class="p">.</span><span class="n">get_x</span><span class="p">()</span> <span class="o">+</span> <span class="n">rect</span><span class="p">.</span><span class="n">get_width</span><span class="p">()</span> <span class="o">/</span> <span class="mi">2</span><span class="p">,</span> <span class="n">height</span><span class="o">+</span><span class="mi">1</span><span class="p">,</span> <span class="nb">str</span><span class="p">(</span><span class="n">height</span><span class="p">),</span> <span class="n">ha</span><span class="o">=</span><span class="s">"center"</span><span class="p">,</span> <span class="n">va</span><span class="o">=</span><span class="s">"bottom"</span><span class="p">)</span>
</code></pre></div></div>]]></content><author><name>冬瓜</name><email>gua@desgard.com</email></author><category term="冬瓜买房笔记" /><category term="数学建模" /><summary type="html"><![CDATA[我给自己定了一个将近 700 天的计划，这就是在上海买房定居。于是开启了研究购房政策、研究小区和板块、研究购房注意事项等一系列的调研和研究。我将这些笔记归档成文章，发表在公众号与大家分享。 今天距离购房还有 675 天。 这篇文章来讨论使用公积金贷款买房的最大化省钱空间。以下讨论均针对于上海市。因为公积金贷款比商业贷款利率低了近两个点，所以公积金贷款也是购房者的首选。下面我来较为全面的记录一下公积金贷款的所有细节问题。 使用公积金贷款的条件 购买上海市具有所有权的自住住房； 申请贷款前 6 个月连续正常缴存住房公积金； 借款人家庭没有尚未还清的公积金债务； 利率数据 首先先给出公积金贷款的贷款利率（以下表内加粗为一般大家所需要关注的数据）： 贷款年限 首套房、二套房普通住宅（基准利率 - 2015.4.8 起开始执行） 二套房非普通住宅（1.1 倍利率） 五年以下（包含五年） 2.75% 3.025% 五年以上 3.25% 3.575% 最高贷款额度 这里不讨论非普通住宅。 普通住宅：按所在地一般民用住宅建筑标准来建造的作为居住用途的房屋，目前多为多层住宅与高层住宅。 非普通住宅：非普通住宅一般指宅建筑面积较大或用作商业用途的房子。 所购住房 首套房 首套房 二套房普通 二套房普通 贷款家庭 1 人贷款 ≥ 2 人贷款 1 人贷款 ≥ 2 人贷款 缴纳住房公积金最高可贷金额 50 万 100 万 50 万 100 万 缴纳补充公积金最高可贷金额 10 万 20 万 10 万 20 万 可贷金额总计 60 万 120 万 60 万 120 万 首付比列 ≤ 90 平米，不低于 20%; ＞ 90 平米不低于 30% 同左 不低于 30\% 同左 这里面我们可以发现住房公积金和补充公积金是有个上限值，但是如何出自己的可贷公积金的数值呢？其实是有如下计算公式：假如我们另当前住房公积金账户余额是，补充公积金账户余额是，则最高可贷金额有如下关系： \[\begin{cases} f(x, y)=40x+20y \\ 40x \leq 50 \times 10^{4} \\ 20y \leq 10 \times 10^{4} \end{cases}\] 通俗的翻译过来就是，公积金最高可贷金额 = 住房公积金余额 × 40 + 补充公积金余额 × 20。所以通过不等式反解我们可得，如果我们想最大的利用公积金，那么我们住房公积金最少需要有 12500 元的余额、补充公积金需要有 5000 块钱的余额，就满足了最高可贷金额的条件。 贷款年限和贷款人年龄限制 首先，如果是新建商品房，也就是房龄为 0 年的房子，最长贷款年限是 30 年。然后我们说二手房，它有以下规则： 房龄 最长贷款年限 ≤ 5 年 30 年 6 - 19 年 35 年 - 房龄（假如是 10 年房龄，则最高可贷 25 年） ≥ 20 年 15 年 贷款算法 同商业贷款的算法相同，公积金贷款也分成等额本金和等额本息两种算法。考虑到更多的人愿意均摊风险以及银行希望获取到更高的利息收入，所以这里我均采用等额本息来计算还款总额。 每月月供 \[月供额 = \frac{月利率 \times (1+月利率)^{还款月数}}{(1+月利率)^{还款月数} - 1} \times 贷款本金\] 其中月利率的计算方法： \[月利率 = \frac{年利率}{12}\] 其他约束 除了我们上文提到的公积金余额对于贷款的约束，我们还要考虑房龄所带来的影响： \[还款月数 = (35 - 房龄) \times 12\] 举例计算 以上就是我们要考虑的所有月数条件，那么我们来举一个例子来进行计算。假如我们现在要买一个 2010 年（房龄 10 年的二手房），总价是 400 万。使用了 35\% 的首付比例之后，我们需要贷款 260 万，最长贷款时间 25 年，也就是还款月数 300 个月。 情况一：全部使用商业贷款 先要确定一下商业贷款的利息，我这里查阅了一下资料，由于上海的商贷金额往往较高，银行会对利息进行 95 折的优惠，从 4.9\% 的基准利率下调到 4.655\%。但今年国家出了 LPR 的利息策略，我们用当前 8 月份的 LPR 利息 4.65\% 来计算。首先来算月利率： \[月利率 = \frac{4.65\%}{12} = 0.003875\] 然后我们来带入计算月供： \[\begin{split} 月供额 &amp;= \frac {0.003875 \times (1 + 0.003875)^{300}}{(1 + 0.003875)^{300} - 1} \times 2.6 \times 10^6 \\ &amp;\approx 14673.899\ 元 \end{split}\] \[\begin{equation} \begin{split} 月供额 &amp;= \frac {0.003875 \times (1 + 0.003875)^{300}}{(1 + 0.003875)^{300} - 1} \times 2.6 \times 10^6 \\ &amp;\approx 14673.899\ 元 \end{split} \end{equation}\] 使用月供额来乘以 30 个月算出总还款： \[总还款 = 30 * 14673.899 = 4402169.7\ 元\] 情况二：使用最大组合贷 由于公积金贷款只能贷 120 万，所以采用 120 万是公积金贷，利息是五年以上的 3.75\%。我们用当前 8 月份的 LPR 利息 4.65\% 当做商业贷款的利息，商业贷款 140 万。 同上述计算法相同，带入公式。 ① 公积金贷款 公积金贷款的月供： \[公积金月供 \approx 6169.57 元\] 300 个月公积金总还款： \[公积金总还款 = 1850871 \ 元\] ② 商业贷款 商业贷款月供： \[商业贷款月供 \approx 7901.33\ 元\] 300 个月商贷总还款： \[商贷总还款 = 2370399元\] 我们得到总还款数： \[总还款 = 1850871 + 2370399 = 4221270 元\] 结果分析 从上面的计算结果来看，我们购买房龄为 10 年的二手房，加入总价为 400 万元，则选择组合贷可以节省 180900 元。 数据分析 上面已经给出了等额本息的计算方法。所以接下来进行控制变量，我们让贷款年限映射到正实数区间，让其投影在 5 年与 30 年之间。保证贷款金额为 400 万。然后我们来计算纯商贷和使用组合贷的数据。蓝色线代表使用纯商贷模式，红色线代表使用组合贷模式。 由图一可以看出，还款年份数越多，其所需还款金额越多，也就意味着利息越高。而红（组合贷）与蓝（纯商贷）的差距也越来越大。并且由右图可知，当还款年份数越多，组合贷的优势愈加明显。 总结 接下来我们来总结一下买房贷款的最大化利益策略： 所以贷款买房尽量可以使用公积金贷款。可贷最大公积金额度需要我们以及我们的配偶具有住房公积金余额 12500 元、补充公积金余额 5000 元。 根据最大贷款额原则（之后会讲到，结论是“首套房付最少的首付，用最大的杠杆贷最多的款，选择 30 年等额本息法，拒不提前还款”策略可达最大收益），当我们将还款时间设置为 30 年的上限阈值，在公积金贷款中也可以获得最大化的成本节约。当然，这就要求我们购买新房和房龄小的二手房。 如果你有任何问题以及更好的建议，可以在下方评论区留言。 相关数据分析代码 以下代码由我个人编写，可在 Jupyter Notebook 环境下直接运行。 """等额本息算法描述""" import numpy as np import math # 等额本息算法 def averageCapitalPlusInterest(principal, anualInterestRate, month): """ principal 表示贷款总额, anualInterestRate 表示年利率, month 表示房贷月份 """ # 计算每月应还款金额 monthlyPayment = np.around(principal * averageCapitalPlusInterestRate(month, monthlyInterestRate(anualInterestRate)), 2) # 还款总额 totalPayment = np.around(monthlyPayment * month, 2) return totalPayment # 计算每月利率 def monthlyInterestRate(anualInterestRate): s = anualInterestRate / 12 return s # 计算比例系数 def averageCapitalPlusInterestRate(month, monthlyInterestRate): R = monthlyInterestRate N = month I = R * math.pow(1 + R, N) / (math.pow(1 + R, N) - 1) return I """贷款数据模拟""" # 全商贷 r = 0.0465 ms = [12 * mi for mi in range(6, 31)] t = 4000000 res = [] for m in ms: res.append(averageCapitalPlusInterest(t, r, m)) res = [np.around(x / 10000, 2) for x in res] # 组合贷 r1 = 0.0465 r2 = 0.0375 t2 = 1200000 t1 = t - t2 rest = [] for m in ms: rest.append(averageCapitalPlusInterest(t1, r1, m) + averageCapitalPlusInterest(t2, r2, m)) rest = [np.around(x / 10000, 2) for x in rest] """做图""" import matplotlib.pyplot as plt year = [m // 12 for m in ms] plt.subplot(221) plt.plot(year, res) plt.plot(year, rest, 'r') plt.xlabel("Loan Time - Year") plt.ylabel("Repayment Amount - RMB") plt.subplot(222) detal = [] for i in range(len(res)): detal.append(res[i] - rest[i]) rects = plt.bar(year, detal) plt.xlabel("Loan Time - Year") plt.ylabel("Savings - RMB") for rect in rects: height = np.around(rect.get_height(), 1) plt.text(rect.get_x() + rect.get_width() / 2, height+1, str(height), ha="center", va="bottom")]]></summary></entry></feed>