<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:media="http://search.yahoo.com/mrss/">
  <channel>
    <title>Efficiency · 仁才德</title>
    <link>https://jared.lynskey.co.nz/zh-cn/tags/efficiency/</link>
    <description>关于软件工程与研发团队领导力的短文——绩效评估、招聘与团队扩张、CI/CD、DevOps 监控、智能体 AI。写于首尔。</description>
    <generator>Hugo</generator>
    <language>zh-CN</language>
    <copyright>© 2026 仁才德</copyright>
    <lastBuildDate>Sat, 07 Nov 2026 00:00:00 +1300</lastBuildDate>
    <atom:link href="https://jared.lynskey.co.nz/zh-cn/tags/efficiency/index.xml" rel="self" type="application/rss+xml" />
    <item>
      <title>pytest 加速：用 pytest-testmon 只跑受代码改动影响的测试</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-10-26-pytest-testmon/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2026/2026-10-26-pytest-testmon/</guid>
      <pubDate>Mon, 26 Oct 2026 00:00:00 +1300</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Python</category>
      <category>Django</category>
      <category>pytest</category>
      <category>Testing</category>
      <category>Test Impact Analysis</category>
      <category>CI/CD</category>
      <category>GitHub Actions</category>
      <category>Claude Code</category>
      <category>AI Agents</category>
      <category>Efficiency</category>
      <description>pytest-testmon 只跑改动能触及的测试，依据是覆盖率记录而不是猜测。把它加进 2,248 个测试的 Django 套件、它需要的包装脚本，以及 Python 3.14 的一个坑。</description>
      <content:encoded><![CDATA[<p><a href="https://www.testmon.org/"  target="_blank" rel="noreferrer">pytest-testmon</a> 是一个 pytest 插件，只跑你的改动可能影响到的测试。它借助 coverage.py 观察每个测试执行了哪些代码行，并为测试碰过的每个代码块存一个校验和。下次运行时，它把这些校验和与磁盘上的代码对比，只跑代码块有变化的测试，再加上上次失败的测试，所以它顺带也干了 <code>pytest --lf</code> 的活。</p>
<p>这类技术统称测试影响分析（test impact analysis），而 testmon 是在 Python 里免费、开源地用上它的一种办法。它完全不依赖 git：它对比的是上次运行时看到的代码，提交没提交都一样。</p>
<p>这周我把它加进了我那个集市应用的 Python 测试里，原因并不是为了快而快。</p>
<figure>
  <div class="mc-film">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRmYAAABXRUJQVlA4IFoAAADwBACdASogABIAPw1wqUqmIyGYDAQAYxDE9IAAS3igrsLc+giUXH/mz758faBcoAAA/vVl8+gZ7GYAPuvC1znoo64X/UaaVXzZOS4gxmDEyDUzHvkl6JAAAAA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/testmon-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <script>window.mcFilm && window.mcFilm()</script><figcaption>这篇文章的约八分钟视频版。旁白是英文，配有中文字幕。</figcaption>
</figure>


<h2 class="relative group">为什么要加它
    <div id="为什么要加它" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88%e8%a6%81%e5%8a%a0%e5%ae%83" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>一个功能需求通常很小：一个界面、一个接口、一条要换个做法的规则。跑整个测试套件，让每个需求都变得比它本身更大。这个套件有 2,248 个 Django 测试，四个进程跑大约三分半，单进程要 11 分钟，而每次编辑都会把它整个跑一遍，尽管其中几乎全部检查的都是这个需求根本没碰过的东西。只要有不相干的测试失败，或者运行单纯慢了点，功能就得等着。拖住它的，是功能需求之外的情况，而那个拖住它的东西，正是我自己的测试套件。</p>
<p>另一条路也好不到哪儿去：不跑全量，猜哪个测试文件覆盖了这次改动，偶尔猜错。这样是快，但不精确，而我发出去的每一个未经测试的改动，都是一个要做两遍的功能需求。</p>
<p>我等的测试应该恰好是这次改动能触及的那些，不多也不少。testmon 给我的这组测试来自记录，而不是猜测。全量套件照样在跑，只不过是在 CI 里，不会拖住我接下来手上的任何事。</p>

<h2 class="relative group">它怎么决定跑什么
    <div id="它怎么决定跑什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%83%e6%80%8e%e4%b9%88%e5%86%b3%e5%ae%9a%e8%b7%91%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>testmon 把每个 Python 文件切成代码块：模块的顶层、每个类、每个函数，嵌套函数的函数体会从外层代码块里切出去。它为每个代码块存一个校验和，从不存代码本身。测试运行时，coverage.py 记录它执行的代码行，testmon 记下这些行属于哪些代码块。没有静态分析，也不靠 import 去猜。一个测试依赖的，恰好就是它跑过的那些代码块。</p>
<p>拿这样一个模块来说：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-python" data-lang="python"><span class="line"><span class="cl"><span class="c1"># pricing.py</span>
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">subtotal</span><span class="p">(</span><span class="n">items</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="n">item</span><span class="o">.</span><span class="n">price</span> <span class="o">*</span> <span class="n">item</span><span class="o">.</span><span class="n">quantity</span> <span class="k">for</span> <span class="n">item</span> <span class="ow">in</span> <span class="n">items</span><span class="p">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="k">def</span> <span class="nf">discount</span><span class="p">(</span><span class="n">total</span><span class="p">,</span> <span class="n">code</span><span class="p">):</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="n">code</span> <span class="o">==</span> <span class="s2">&#34;WELCOME10&#34;</span><span class="p">:</span>
</span></span><span class="line"><span class="cl">        <span class="k">return</span> <span class="n">total</span> <span class="o">*</span> <span class="mf">0.9</span>
</span></span><span class="line"><span class="cl">    <span class="k">return</span> <span class="n">total</span></span></span></code></pre></div></div>
<p>一个只调用 <code>subtotal()</code> 的测试，依赖的是模块顶层和 <code>subtotal</code> 的函数体。<code>discount()</code> 随你怎么改写，testmon 都不会重跑这个测试，因为它从没执行过 <code>discount</code> 里的任何一行。而在 <code>subtotal</code> 里哪怕只改一个字符，它就会再跑一次，即使这个改动根本不可能改变结果。testmon 不会在副作用上耍聪明：你执行过的代码块变了，你就得跑。</p>
<p>它还会追踪代码周围的东西。记录里包括 Python 版本，以及已安装的包及其版本。它不看环境变量：同一份代码要在两个 settings 模块下跑的话，得用 <code>--testmon-env</code>（第 8 步）给它们起名字，否则它们共用一份记录。升级一下 Django，所有碰过 Django 的东西都会再次受影响，而在一个 Django 应用里，那就是全部。</p>

<h2 class="relative group">它看不到什么
    <div id="它看不到什么" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%83%e7%9c%8b%e4%b8%8d%e5%88%b0%e4%bb%80%e4%b9%88" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>testmon 追踪的是测试执行的 Python 代码。测试读取的其他文件它不追踪：模板、JSON、文本，磁盘上的任何别的东西。经网络访问的服务它也不追踪。而在测试开始前只跑一次的东西，它没法归到某个具体测试头上。</p>
<p>放在 Django 项目里，首先是迁移：它们只在创建测试数据库时跑一次，所以没有哪个测试的记录里包含它们（有新迁移时，下面的包装脚本会重建测试数据库）。其次是设置和启动代码，它们在 pytest 启动时运行，不属于任何一个测试。再就是模板和数据文件：模板不是 Python，所以改了模板，渲染它的测试一个都不会重跑。</p>
<p>我的测试套件还有几样自己特有的。有些测试读取一个 JSON fixture 文件，移动应用的测试也共用它。有些检查构建出来的 Web bundle，还有些检查同一个仓库里生成的静态网站的输出。改了其中任何一个，testmon 都会高高兴兴地告诉你什么都不用跑。所以下面的教程会用一个脚本把 testmon 包起来，这个脚本会留意这些文件，只要其中一个改了，就全部跑一遍。</p>

<h2 class="relative group">怎么把它加进 Django 项目
    <div id="怎么把它加进-django-项目" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%80%8e%e4%b9%88%e6%8a%8a%e5%ae%83%e5%8a%a0%e8%bf%9b-django-%e9%a1%b9%e7%9b%ae" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>以下步骤假定你用 pytest 和 <a href="https://pytest-django.readthedocs.io/"  target="_blank" rel="noreferrer">pytest-django</a>，依赖用 uv 管理。用 pip 的话，把 <code>uv add --dev</code> 换成 <code>pip install</code>，去掉 <code>uv run</code>。</p>
<p><strong>1. 安装。</strong></p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">uv add --dev pytest-testmon</span></span></code></pre></div></div>
<p><strong>2. 确保 pytest 能跑这套测试。</strong> testmon 是 pytest 插件，所以在 <code>python manage.py test</code> 下它什么都不做。pytest-django 需要知道设置模块，以及你的测试所用的文件命名模式：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ini" data-lang="ini"><span class="line"><span class="cl"><span class="c1"># pytest.ini</span>
</span></span><span class="line"><span class="cl"><span class="k">[pytest]</span>
</span></span><span class="line"><span class="cl"><span class="na">DJANGO_SETTINGS_MODULE</span> <span class="o">=</span> <span class="s">myproject.settings</span>
</span></span><span class="line"><span class="cl"><span class="na">python_files</span> <span class="o">=</span> <span class="s">tests.py test_*.py *_tests.py</span>
</span></span><span class="line"><span class="cl"><span class="na">python_classes</span> <span class="o">=</span> <span class="s">Test* *Tests *TestCase</span></span></span></code></pre></div></div>
<p>如果这套测试一直只在 Django 自带的 runner 下跑过，先在 pytest 下跑一遍，把不一致的地方修好，再加 testmon。不然你就得同时调试两件事。</p>
<p><strong>3. 别把记录放进 git。</strong> testmon 会在 pytest 根目录写入 <code>.testmondata</code>。它是一个 SQLite 数据库，所以旁边还会出现 <code>-shm</code> 和 <code>-wal</code> 文件，下面的脚本还会再加一个时间戳文件。一个模式就能把它们全部覆盖：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-text" data-lang="text"><span class="line"><span class="cl"># .gitignore
</span></span><span class="line"><span class="cl">.testmondata*</span></span></code></pre></div></div>
<p><strong>4. 先把整套测试记录一遍。</strong> testmon 在看过每个测试运行之前，什么都选不出来：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">uv run pytest --testmon</span></span></code></pre></div></div>
<p>在全新的检出里，第一次运行就是单进程跑完整个套件。在我这里，2,248 个测试大约要 12 分钟。从那以后，同一条命令就只跑受影响的测试。什么都没改的话，它什么都不跑。</p>
<p>有两个坑。在 testmon 2.2.0 及更早版本上，它需要 pytest 的 cache 插件：我第一次尝试时带着 <code>-p no:cacheprovider</code>，结果以 <code>KeyError: 'lf'</code> 崩掉了（2.3.0 会把缺失的 <code>--lf</code> 当作未设置）。另外，在 Python 3.14 或更高版本上，记录之前要先设置 <code>COVERAGE_CORE=ctrace</code>。原因在后面的“看起来全绿的那个 bug”一节里解释。这是下面脚本里最重要的一行。</p>
<p>更新（11 月 7 日）：11 月 2 日发布的 testmon 2.3.0 会自己强制使用 coverage 的 C tracer，所以在这个版本上，这行 export 只是多一道保险。如果你用的是 2.2.0 或更早的版本，就留着它。而故意弄坏点什么来验证的那一步，不管哪个版本都要做。</p>
<p><strong>5. 为它看不到的文件包一层。</strong> 正是这一步，让它可以放心地天天用。脚本保留一个时间戳文件，记的是上次运行开始的时间。只要有任何 testmon 追踪不到的文件比这个时间戳新，就全部跑一遍并重新记录。新的迁移只会让它重建测试数据库。其余情况就让 testmon 来选。删减后的示例：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="cp">#!/usr/bin/env bash
</span></span></span><span class="line"><span class="cl"><span class="c1"># scripts/test-changed.sh: the tests a change can affect, or all when in doubt.</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   scripts/test-changed.sh            # affected tests</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   scripts/test-changed.sh --all      # everything, re-recorded</span>
</span></span><span class="line"><span class="cl"><span class="c1">#   scripts/test-changed.sh -k orders  # anything else goes to pytest</span>
</span></span><span class="line"><span class="cl"><span class="nb">set</span> -euo pipefail
</span></span><span class="line"><span class="cl"><span class="nb">cd</span> <span class="s2">&#34;</span><span class="k">$(</span>dirname <span class="s2">&#34;</span><span class="nv">$0</span><span class="s2">&#34;</span><span class="k">)</span><span class="s2">/..&#34;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># coverage&#39;s C tracer: from Python 3.14 coverage defaults to sys.monitoring,</span>
</span></span><span class="line"><span class="cl"><span class="c1"># which reports a line only the first time a process runs it, so testmon</span>
</span></span><span class="line"><span class="cl"><span class="c1"># would credit each line to one test. Changing this means --all.</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">COVERAGE_CORE</span><span class="o">=</span>ctrace
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">STAMP</span><span class="o">=</span>.testmondata.started
</span></span><span class="line"><span class="cl"><span class="nv">full</span><span class="o">=</span><span class="nb">false</span>
</span></span><span class="line"><span class="cl"><span class="nv">rebuild</span><span class="o">=</span><span class="nb">false</span>
</span></span><span class="line"><span class="cl"><span class="k">if</span> <span class="o">[</span> <span class="s2">&#34;</span><span class="si">${</span><span class="nv">1</span><span class="k">:-</span><span class="si">}</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="s2">&#34;--all&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nv">full</span><span class="o">=</span>true<span class="p">;</span> <span class="nb">shift</span>
</span></span><span class="line"><span class="cl"><span class="k">elif</span> <span class="o">[</span> ! -f .testmondata <span class="o">]</span> <span class="o">||</span> <span class="o">[</span> ! -f <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">    <span class="nb">echo</span> <span class="s2">&#34;No record yet: running everything once.&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="nv">full</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="k">else</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># Changed since the last run started, and not traceable per test:</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># anything that isn&#39;t Python, plus settings and conftest.</span>
</span></span><span class="line"><span class="cl">    <span class="nv">newer</span><span class="o">=</span><span class="s2">&#34;</span><span class="k">$(</span>find myapp myproject fixtures pytest.ini <span class="se">\
</span></span></span><span class="line"><span class="cl">        -type f -newer <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> ! -path <span class="s1">&#39;*/migrations/*&#39;</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        <span class="se">\(</span> ! -name <span class="s1">&#39;*.py&#39;</span> -o -path <span class="s1">&#39;myproject/settings*&#39;</span> -o -name <span class="s1">&#39;conftest.py&#39;</span> <span class="se">\)</span> <span class="se">\
</span></span></span><span class="line"><span class="cl">        ! -path <span class="s1">&#39;*/__pycache__/*&#39;</span> <span class="p">|</span> head -5<span class="k">)</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl">    <span class="k">if</span> <span class="o">[</span> -n <span class="s2">&#34;</span><span class="nv">$newer</span><span class="s2">&#34;</span> <span class="o">]</span><span class="p">;</span> <span class="k">then</span>
</span></span><span class="line"><span class="cl">        <span class="nb">echo</span> <span class="s2">&#34;Changed, and not traceable per test:&#34;</span><span class="p">;</span> <span class="nb">printf</span> <span class="s1">&#39;  %s\n&#39;</span> <span class="nv">$newer</span>
</span></span><span class="line"><span class="cl">        <span class="nv">full</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl">    <span class="k">fi</span>
</span></span><span class="line"><span class="cl">    <span class="c1"># A new migration needs a fresh test database, not a full run.</span>
</span></span><span class="line"><span class="cl">    <span class="o">[</span> -n <span class="s2">&#34;</span><span class="k">$(</span>find myapp -path <span class="s1">&#39;*/migrations/*.py&#39;</span> -newer <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> <span class="p">|</span> head -1<span class="k">)</span><span class="s2">&#34;</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">rebuild</span><span class="o">=</span><span class="nb">true</span>
</span></span><span class="line"><span class="cl"><span class="k">fi</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="c1"># Stamp the start, so an edit made while the tests run counts next time.</span>
</span></span><span class="line"><span class="cl"><span class="nv">started</span><span class="o">=</span><span class="s2">&#34;</span><span class="k">$(</span>mktemp .testmondata.run.XXXXXX<span class="k">)</span><span class="s2">&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nv">args</span><span class="o">=(</span>--testmon --reuse-db<span class="o">)</span>
</span></span><span class="line"><span class="cl"><span class="c1"># --create-db alone deletes the database when the run ends; with</span>
</span></span><span class="line"><span class="cl"><span class="c1"># --reuse-db as well, the rebuilt one is kept for next time.</span>
</span></span><span class="line"><span class="cl"><span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$rebuild</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="nb">true</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">args</span><span class="o">=(</span>--testmon --reuse-db --create-db<span class="o">)</span>
</span></span><span class="line"><span class="cl"><span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$full</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="nb">true</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nv">args</span><span class="o">=(</span>--testmon-noselect --reuse-db --create-db<span class="o">)</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="nv">status</span><span class="o">=</span><span class="m">0</span>
</span></span><span class="line"><span class="cl">uv run pytest <span class="s2">&#34;</span><span class="si">${</span><span class="nv">args</span><span class="p">[@]</span><span class="si">}</span><span class="s2">&#34;</span> -q <span class="s2">&#34;</span><span class="nv">$@</span><span class="s2">&#34;</span> <span class="o">||</span> <span class="nv">status</span><span class="o">=</span><span class="nv">$?</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 0: passed, or nothing selected. 1: some failed (still recorded).</span>
</span></span><span class="line"><span class="cl"><span class="c1"># 5: nothing collected at all.</span>
</span></span><span class="line"><span class="cl"><span class="k">case</span> <span class="s2">&#34;</span><span class="nv">$status</span><span class="s2">&#34;</span> in 0<span class="p">|</span>1<span class="p">|</span>5<span class="o">)</span> mv <span class="s2">&#34;</span><span class="nv">$started</span><span class="s2">&#34;</span> <span class="s2">&#34;</span><span class="nv">$STAMP</span><span class="s2">&#34;</span> <span class="p">;;</span> *<span class="o">)</span> rm -f <span class="s2">&#34;</span><span class="nv">$started</span><span class="s2">&#34;</span> <span class="p">;;</span> <span class="k">esac</span>
</span></span><span class="line"><span class="cl"><span class="o">[</span> <span class="s2">&#34;</span><span class="nv">$status</span><span class="s2">&#34;</span> <span class="o">=</span> <span class="m">5</span> <span class="o">]</span> <span class="o">&amp;&amp;</span> <span class="nb">exit</span> <span class="m">0</span>
</span></span><span class="line"><span class="cl"><span class="nb">exit</span> <span class="s2">&#34;</span><span class="nv">$status</span><span class="s2">&#34;</span></span></span></code></pre></div></div>
<p>这里面有两个细节值得解释。<code>--reuse-db</code> 是 pytest-django 的参数，用来在两次运行之间保留测试数据库。一旦一次运行只要几秒，这一点就很要紧：每次重新创建数据库，花的时间可能比测试本身还长。全量运行，或者有新迁移之后的那次运行，会再加上 <code>--create-db</code>，让数据库用上当前的 schema。<code>--reuse-db</code> 要和它一起留着：单独用 <code>--create-db</code> 时，pytest-django 会在运行结束时删掉数据库，下一次运行就得从头再建一遍。</p>
<p>还有，当 testmon 把所有测试都取消选中时，运行的退出码是 0，所以“什么都没改”算作通过。退出码 5 是 pytest 的 &ldquo;no tests collected&rdquo;（没有收集到测试），脚本把它也当作没问题。</p>
<p>注意清单里没有什么：<code>pyproject.toml</code> 和 lock 文件。我的第一版只要 lock 文件一变就全部跑一遍，结果这个慢吞吞的兜底大多数日子都会触发，整件事比以前还糟。testmon 本身就会追踪已安装包的版本，用不着帮这个忙。</p>
<p><strong>6. 给它单独的数据库和缓存。</strong> 如果同一台机器上还有别的东西在跑测试，比如第二个终端、一个编程 agent 或者 <code>manage.py test</code>，就让脚本指向它自己的测试数据库和它自己的缓存编号，这样保留下来的数据库永远不会撞上别人的运行：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">DATABASE_URL</span><span class="o">=</span><span class="s2">&#34;postgresql://myapp:myapp@localhost:5432/myapp_changed&#34;</span>
</span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">REDIS_URL</span><span class="o">=</span><span class="s2">&#34;redis://localhost:6379/8&#34;</span></span></span></code></pre></div></div>
<p><strong>7. 每次运行前清空那个缓存。</strong> 这一条我是吃了亏才学到的。子集运行开始出现 <code>KeyError</code>，全量运行却没有。有些分类标签的缓存没有过期时间，于是一次运行保留下来的测试数据库，碰上了更早一次运行留下、还热着的缓存。在脚本开头清掉缓存，问题就解决了：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">uv run python -c <span class="s2">&#34;import os, redis; redis.Redis.from_url(os.environ[&#39;REDIS_URL&#39;]).flushdb()&#34;</span></span></span></code></pre></div></div>
<p>这正是 testmon 在做它文档里说过会做的事：每次跑不同的子集，会暴露出那些只是因为之前跑过什么才通过的测试。修复应该放在测试的 setup 里，而不是 testmon 里。</p>
<p><strong>8. 记住选择出错时用的参数。</strong></p>
<ul>
<li><code>--testmon-noselect</code> 跑所有测试，但把可能失败的排在前面。当你同时传了 <code>-k</code>、<code>-m</code>、<code>--lf</code> 或某个测试的 node ID 时，testmon 会自动切换到这个模式。</li>
<li><code>--testmon-forceselect</code> 只跑既受影响、又匹配你的 <code>-k</code> 或 <code>-m</code> 的测试。</li>
<li><code>--testmon-nocollect</code> 使用已有的记录，但不往里添加。在调试器下，或者 coverage 已经在运行时，会强制使用这个模式。</li>
<li><code>--no-testmon</code> 在它写进了 <code>addopts</code> 时，用来关掉一次运行。</li>
<li><code>--testmon-env=&lt;name&gt;</code> 在一个文件里保存多份独立的记录，适合要在两个设置模块下跑的测试套件。</li>
</ul>
<p>如果项目还有 JavaScript 那一侧，Jest 自带了同类功能。<code>jest --changedSince=main</code> 会跑那些 import 了自 <code>main</code> 以来改动过的任何东西的测试，它跟的是 import，而不是覆盖率。我把它加进了应用的 <code>package.json</code>，叫 <code>npm run test:changed</code>，这样两边是同一个习惯。改了一个工具模块，它从应用的 121 个测试文件里选中了 7 个。</p>

<h2 class="relative group">它能省下多少
    <div id="它能省下多少" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%ae%83%e8%83%bd%e7%9c%81%e4%b8%8b%e5%a4%9a%e5%b0%91" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>包装脚本就位、并修好下一节说的那个 bug 之后，我计了一下时，包括启动时间：</p>
<table>
	<thead>
			<tr>
					<th>改了什么</th>
					<th style="text-align: right">跑的测试数</th>
					<th style="text-align: right">耗时</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td>什么都没改</td>
					<td style="text-align: right">0</td>
					<td style="text-align: right">1.0 s</td>
			</tr>
			<tr>
					<td>改了一处首页横幅背后的代码</td>
					<td style="text-align: right">17</td>
					<td style="text-align: right">8.5 s</td>
			</tr>
			<tr>
					<td>撤销那处改动</td>
					<td style="text-align: right">17</td>
					<td style="text-align: right">8.7 s</td>
			</tr>
			<tr>
					<td>整个套件，作为对照（4 个进程）</td>
					<td style="text-align: right">2,248</td>
					<td style="text-align: right">约 3½ min</td>
			</tr>
	</tbody>
</table>
<p>日常的一次编辑，比并行跑整个套件快大约 25 倍；什么都没改的时候，快大约两百倍。</p>
<p>这份记录从更宽的角度说明了同一件事。在测试套件跑的 307 个非测试 Python 文件中，改动中位数的那个文件会波及 22 个测试，测试时间大约 8 秒。另一头是几个核心模块：几乎每个测试都会跑到它们，所以改了那里会波及 1,500 个左右的测试，testmon 会重跑套件的大部分。这才是正确的答案，不是失败。这些数字是按文件算的上限：testmon 按代码块工作，所以改了一个函数，只会选中跑过那个函数的测试。</p>
<p>代价出现在包装脚本退回全量运行的时候。一次全量运行和第一次一样，是单进程的记录，大约 12 分钟，比它取代的那个并行套件还慢。之所以是单进程，只是因为我还没试过把 testmon 和 pytest-xdist 一起用；它从 1.4 起就支持 xdist，下一个该量的就是这个。所以触发全量运行的文件清单，应该在不自欺的前提下尽量短。</p>

<h2 class="relative group">看起来全绿的那个 bug
    <div id="看起来全绿的那个-bug" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%9c%8b%e8%b5%b7%e6%9d%a5%e5%85%a8%e7%bb%bf%e7%9a%84%e9%82%a3%e4%b8%aa-bug" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>我最早的数字比这些好看：改一处，6 个测试，3.3 秒。它们是错的，而屏幕上没有任何东西提示这一点。</p>
<p>从 Python 3.14 开始，coverage.py 默认使用一个新的核心，建立在解释器的 <code>sys.monitoring</code> 之上。这个核心只在一个进程第一次运行某一行时报告它。testmon 关于哪个测试跑了哪一行的记录，是从 coverage 得来的，所以每一行都只记在碰巧第一个跑到它的测试头上，别的测试一概没有。改一行八个测试共用的代码，testmon 只会选中其中一个。</p>
<p>发现它，是在我另一个更小的项目上，那个项目照搬了这套配置。在那里引入它的步骤之一，就是故意弄坏一行代码、对比结果，而数字对不上。回到这个套件，我做了同样的检查。我弄坏了首页横幅代码里的一行，也就是一张幻灯片的标题。直接跑 pytest，报告了 8 个失败的测试。testmon 选中了 4 个。另外 4 个坏掉的测试根本没跑，输出里也没有任何地方说它们被漏掉了。</p>
<p>修复只要一行，<code>export COVERAGE_CORE=ctrace</code>，让 coverage 回到经典的 C tracer。换了 tracer，记录也就不一样了，所以我重新记录了一遍：2,248 个测试，12 分 3 秒。之后，同样那种弄坏代码的改动，把它弄坏的 11 个测试全都跑了。</p>
<p>更新（11 月 7 日）：11 月 2 日发布的 testmon 2.3.0 现在会自己设置 C tracer，进程内和子进程里都会，所以新装的话不再需要这行 export。下一段里的检查仍然需要。</p>
<p>这是我最想先传下去的一条教训。一个选得太少的测试选择器，看起来和成功一模一样：测试更少，跑得更快，全是绿的。所以搭一个这样的东西时，要故意弄坏某个共用的东西，分别跑原本的完整套件和选择器，确认它们失败的是同一批测试。之后每当 Python 或 coverage.py 升级版本，再做一遍。</p>

<h2 class="relative group">编程 agent 在哪里用得上
    <div id="编程-agent-在哪里用得上" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e7%bc%96%e7%a8%8b-agent-%e5%9c%a8%e5%93%aa%e9%87%8c%e7%94%a8%e5%be%97%e4%b8%8a" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>那个仓库里的改动，已经不全是我自己做的了。一个编程 agent，我用的是 Claude Code，做了很多小改动，而一个好的 agent 每次编辑后都会跑测试。面对一个 11 分钟的测试套件，它的两个坏选择和我当初一样：等，或者猜哪个测试文件要紧。</p>
<p>所以仓库里给 agent 的说明现在写着：工作时跑测试，默认就用这个包装脚本，要全量运行就加 <code>--all</code>。每次编辑后，agent 都能在几秒内拿到和我一样精确的那组测试。这也是第 6 步要给脚本单独的数据库和缓存的原因：忙的时候，同一台机器上不止一个会话在跑测试，而保留下来的数据库绝不能撞上别人的运行。</p>
<p>这些都不需要 testmon 提供任何 AI 专属的东西。还是同一份记录、同一套选择。只不过，当做改动的那一方改得非常多时，它就更重要了。</p>

<h2 class="relative group">为什么 CI 用的是更粗的版本
    <div id="为什么-ci-用的是更粗的版本" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e4%b8%ba%e4%bb%80%e4%b9%88-ci-%e7%94%a8%e7%9a%84%e6%98%af%e6%9b%b4%e7%b2%97%e7%9a%84%e7%89%88%e6%9c%ac" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>testmon 没有 CI 模式。它在 runner 上和在笔记本上表现一样，而它的作者写道，在 CI runner 之间共享或缓存 <code>.testmondata</code>，效果远不如他们的托管服务 testmon.net。缓存下来的记录还会带着上面说的所有盲区，再加上我的 CI 是用 Django 自带的 runner、四个进程跑这套测试的，所以我没在 CI 里用 testmon。</p>
<p>CI 拿到的，是同一个思路的文件级版本。检查工作流现在先跑一个小 job，对这次推送做 diff，判断它碰到了仓库的哪一半：Python API、移动应用、两者都有，或者都没有。在这之前，每次推送 CI 都会把 Python 和应用两个 job 都跑一遍，只改文档的推送也不例外。现在只改文档的推送什么都不跑，只改应用的推送会跳过 Django 测试套件。我拿五个真实的提交试跑了这个 job：只改文档的那个什么都没跑，只改应用的那个跳过了 Python job，只改后端的那个跳过了应用 job。删减后的示例：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-yaml" data-lang="yaml"><span class="line"><span class="cl"><span class="nt">jobs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">changes</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">outputs</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span><span class="nt">python</span><span class="p">:</span><span class="w"> </span><span class="l">${{ steps.diff.outputs.python }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">with</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">fetch-depth</span><span class="p">:</span><span class="w"> </span><span class="m">0</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">id</span><span class="p">:</span><span class="w"> </span><span class="l">diff</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">env</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">BEFORE</span><span class="p">:</span><span class="w"> </span><span class="l">${{ github.event.before }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">          </span><span class="nt">HEAD</span><span class="p">:</span><span class="w"> </span><span class="l">${{ github.sha }}</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">        </span><span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="p">|</span><span class="sd">
</span></span></span><span class="line"><span class="cl"><span class="sd">          FILES=&#34;$(git diff --name-only &#34;$BEFORE&#34; &#34;$HEAD&#34;)&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          # Python&#39;s inputs include the non-Python files its tests read.
</span></span></span><span class="line"><span class="cl"><span class="sd">          PY=&#39;^(myapp/|myproject/|fixtures/shared\.json$|web/dist/|pyproject\.toml$|uv\.lock$)&#39;
</span></span></span><span class="line"><span class="cl"><span class="sd">          if printf &#39;%s\n&#39; &#34;$FILES&#34; | grep -qE &#34;$PY&#34;; then
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;python=true&#34; &gt;&gt; &#34;$GITHUB_OUTPUT&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          else
</span></span></span><span class="line"><span class="cl"><span class="sd">            echo &#34;python=false&#34; &gt;&gt; &#34;$GITHUB_OUTPUT&#34;
</span></span></span><span class="line"><span class="cl"><span class="sd">          fi</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">  </span><span class="nt">python</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">needs</span><span class="p">:</span><span class="w"> </span><span class="l">changes</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">if</span><span class="p">:</span><span class="w"> </span><span class="l">needs.changes.outputs.python == &#39;true&#39;</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">runs-on</span><span class="p">:</span><span class="w"> </span><span class="l">ubuntu-latest</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">    </span><span class="nt">steps</span><span class="p">:</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">uses</span><span class="p">:</span><span class="w"> </span><span class="l">actions/checkout@v7</span><span class="w">
</span></span></span><span class="line"><span class="cl"><span class="w">      </span>- <span class="nt">run</span><span class="p">:</span><span class="w"> </span><span class="l">uv run python manage.py test --parallel 4 --noinput</span></span></span></code></pre></div></div>
<p>真实的版本在没有可比较的范围时，也会全部跑一遍：新分支、强制推送（force push），或者手动运行。</p>
<p>盲区还是同一个，只是换了个形式。testmon 看不到 JSON 文件，路径过滤器也看不到，除非你把它列出来。所以这个模式里明确写出了共享的 fixture、构建出来的 bundle 和生成的网站，还加了一条注释，请改它的人让这份清单保持如实。文件级的版本更粗糙，但它出错时偏向安全的一边：Python 那边只要有任何改动，就跑整个套件。</p>

<h2 class="relative group">值得吗？
    <div id="值得吗" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%80%bc%e5%be%97%e5%90%97" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>对一个要跑好几分钟的测试套件来说，值得。真正的代价在于它看不到的东西，而那正是包装脚本的用处。即便如此，testmon 该待的地方是笔记本上的开发循环。只要 Python 那边有改动，CI 照样跑整个套件，部署前我信任的是那一次运行。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2026/2026-10-26-pytest-testmon/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>咖啡聊天（Coffee Chat）是什么？和面试有什么不同，该问些什么</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-07-12-coffee-chats/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-07-12-coffee-chats/</guid>
      <pubDate>Fri, 12 Jul 2024 00:30:03 +0000</pubDate>
      <dc:creator>Jared Lynskey</dc:creator>
      <category>Engineering Manager</category>
      <category>Team</category>
      <category>People</category>
      <category>Team Size</category>
      <category>Scaling</category>
      <category>Efficiency</category>
      <category>Talent Scouting</category>
      <category>Coffee Chat</category>
      <category>Recruitment</category>
      <category>Hiring</category>
      <category>Culture Fit</category>
      <category>Networking</category>
      <description>咖啡聊天（coffee chat）是在咖啡馆或视频通话里进行的 30–45 分钟非正式对话，用来看双方值不值得深谈，它不是面试。为什么它成了我认识开发者最好用的方式，我怎么安排、问些什么，如果你是被邀请的一方该穿什么、聊什么，以及人们把它搞砸的几种方法。</description>
      <content:encoded><![CDATA[<p>我最想招的开发者从来不在招聘网站上。他们正埋头做自己的产品，对现状还算满意，对猎头消息保持着理所当然的警惕。今年转做工程管理之后，我用来认识这些人的工具简单得有点不好意思：一杯咖啡。</p>
<p>咖啡聊天就是 30–45 分钟的非正式对话，在咖啡馆或视频通话里都行。没有白板，没有面试官团，没有陷阱题。我讲我们在做什么、为什么做，对方讲自己在做什么、接下来想要什么，聊完双方就知道值不值得继续深谈。招聘与其说是筛选问题，不如说是匹配问题，而要交换匹配所需的信息，我不知道还有什么比这更快的办法。</p>
<figure><div class="film-pair">
  <div class="mc-film film-dark">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film-poster.jpg" style="background:url('data:image/webp;base64,UklGRmoAAABXRUJQVlA4IF4AAACwBACdASogABIAPw12qkmmI6GYDAQAYxDE9IABIX0/HUGa/BwFLmQiaci9B73wAP7ouyxmkTX73K2EljbawAtCxwSblm7y7euMLarkzUk+r7wjHZ1dwA9tzx/08AAA') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <div class="mc-film film-light">
  <video
    class="my-0 rounded-md"
    controls playsinline preload="none"
    poster="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film-light-poster.jpg" style="background:url('data:image/webp;base64,UklGRoQAAABXRUJQVlA4IHgAAAAwBQCdASogABIAPw1yq0omI6GYDAQAYxDE9IAECBxAX9Q7kIyd+ZdexoqRRzGjpObyCAD+82xiqEeejshY20Dlsk/rGQ/XxZ1l6LikpJD6mF94kq3JymaOuDWqzKA/RTf0sM9DNRh6p/OQdQxkloY1GBk/Gszp4AA=') center/cover no-repeat"
    width="1280"
    height="720"
    aria-label="讲述这篇文章的一段短片">
    <source src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film-light.webm" type="video/webm">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_en.vtt" srclang="en" label="English">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_ja.vtt" srclang="ja" label="日本語">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_ko.vtt" srclang="ko" label="한국어">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_vi.vtt" srclang="vi" label="Tiếng Việt">
    <track kind="subtitles" src="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/coffee-chats-film_zh-cn.vtt" srclang="zh-cn" label="简体中文" default>
  </video>
  </div>
  <script>(function(){if(window.mcFilm)return window.mcFilm();var a={play:'<path d="M8 5.6v12.8a1 1 0 0 0 1.52.85l10.2-6.4a1 1 0 0 0 0-1.7L9.52 4.75A1 1 0 0 0 8 5.6z"/>',pause:'<rect x="6.5" y="5" width="4" height="14" rx="1.2"/><rect x="13.5" y="5" width="4" height="14" rx="1.2"/>',volume:'<path d="M4 9.5v5a1 1 0 0 0 1 1h3l4.4 3.6a.6.6 0 0 0 1-.47V5.37a.6.6 0 0 0-1-.47L8 8.5H5a1 1 0 0 0-1 1z"/><path d="M16.5 8.5a5 5 0 0 1 0 7M19 6a8.5 8.5 0 0 1 0 12" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>',muted:'<path d="M4 9.5v5a1 1 0 0 0 1 1h3l4.4 3.6a.6.6 0 0 0 1-.47V5.37a.6.6 0 0 0-1-.47L8 8.5H5a1 1 0 0 0-1 1z"/><path d="M16.5 9.5l5 5m0-5l-5 5" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round"/>',cc:'<rect x="3" y="5.5" width="18" height="13" rx="3" fill="none" stroke="currentColor" stroke-width="1.8"/><path d="M10.5 10.3a2.2 2.2 0 1 0 0 3.4M17 10.3a2.2 2.2 0 1 0 0 3.4" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linecap="round"/>',full:'<path d="M4.5 9V5.5a1 1 0 0 1 1-1H9M15 4.5h3.5a1 1 0 0 1 1 1V9M19.5 15v3.5a1 1 0 0 1-1 1H15M9 19.5H5.5a1 1 0 0 1-1-1V15" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>',exit:'<path d="M9 4.5V8a1 1 0 0 1-1 1H4.5M19.5 9H16a1 1 0 0 1-1-1V4.5M15 19.5V16a1 1 0 0 1 1-1h3.5M4.5 15H8a1 1 0 0 1 1 1v3.5" fill="none" stroke="currentColor" stroke-width="1.9" stroke-linecap="round"/>'},s={en:["Play","Pause","Mute","Unmute","Subtitles","Off","Full screen","Exit full screen","Seek"],ko:["재생","일시정지","음소거","음소거 해제","자막","끄기","전체 화면","전체 화면 종료","탐색"],ja:["再生","一時停止","ミュート","ミュート解除","字幕","オフ","全画面","全画面を終了","シーク"],zh:["播放","暂停","静音","取消静音","字幕","关闭","全屏","退出全屏","进度"],vi:["Phát","Tạm dừng","Tắt tiếng","Bật tiếng","Phụ đề","Tắt","Toàn màn hình","Thoát toàn màn hình","Tua"]},r=(document.documentElement.lang||"en").toLowerCase().slice(0,2),e=s[r]||s.en,t=function(e){return'<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">'+a[e]+"</svg>"},o={},i=function(e,t){if(o[e]||typeof window.gtag!="function")return;o[e]=!0;var n=(t.currentSrc||(t.querySelector("source")||{}).src||"").split("/").pop();window.gtag("event",e,{film:n.replace(/-light(?=\.)/,"")})},n=function(e){(!isFinite(e)||e<0)&&(e=0),e=Math.floor(e);var t=Math.floor(e/3600),n=Math.floor(e%3600/60),s=String(e%60).padStart(2,"0");return t?t+":"+String(n).padStart(2,"0")+":"+s:n+":"+s};function c(s){var a,r,c,d,u,m,p,g,v,b,j,_,w,O,C,E,k,A,o=s.querySelector("video");if(!o)return;s.classList.add("is-ready"),o.controls=!1,o.removeAttribute("controls"),s.insertAdjacentHTML("beforeend",'<button type="button" class="mc-film__big" aria-label="'+e[0]+'">'+t("play")+'</button><div class="mc-film__bar"><button type="button" class="mc-film__btn" data-act="play" aria-label="'+e[0]+'">'+t("play")+'</button><span class="mc-film__time"><span data-cur>0:00</span><span class="mc-film__of"> / </span><span data-dur>0:00</span></span><input class="mc-film__seek" type="range" min="0" max="1000" step="1" value="0" aria-label="'+e[8]+'"><span class="mc-film__cc"><button type="button" class="mc-film__btn" data-act="cc" aria-label="'+e[4]+'" aria-haspopup="true" aria-expanded="false">'+t("cc")+'</button><span class="mc-film__menu" role="menu" hidden></span></span><button type="button" class="mc-film__btn" data-act="mute" aria-label="'+e[2]+'">'+t("volume")+'</button><button type="button" class="mc-film__btn" data-act="full" aria-label="'+e[6]+'">'+t("full")+"</button></div>"),A=s.querySelector(".mc-film__big"),a=s.querySelector(".mc-film__bar"),j=a.querySelector('[data-act="play"]'),p=a.querySelector('[data-act="mute"]'),u=a.querySelector('[data-act="full"]'),d=a.querySelector('[data-act="cc"]'),r=a.querySelector(".mc-film__menu"),c=a.querySelector(".mc-film__seek"),w=a.querySelector("[data-cur]"),O=a.querySelector("[data-dur]"),g=!1,v=0,b=function(){return Array.prototype.filter.call(o.textTracks,function(e){return e.kind==="subtitles"||e.kind==="captions"})},b().length||(d.parentNode.hidden=!0),_=null;function f(e){var n,i,t=!s.classList.contains("is-idle")&&s.classList.contains("is-started");if(e!==!0&&t===_)return;_=t,n=o.clientHeight,i=n?Math.max(40,100-(a.offsetHeight+22)/n*100):85,b().forEach(function(e){if(e.mode!=="showing"||!e.cues)return;for(var n,s=0;s<e.cues.length;s++)n=e.cues[s],t?(n.snapToLines=!1,n.line=i,n.lineAlign="end"):(n.snapToLines=!0,n.line="auto",n.lineAlign="start")})}m=function(){f(!0)},window.addEventListener("resize",m),Array.prototype.forEach.call(o.querySelectorAll("track"),function(e){e.addEventListener("load",m)});function y(){o.paused||o.ended?o.play().catch(function(){}):o.pause()}function l(){s.classList.remove("is-idle"),f(),clearTimeout(v),v=setTimeout(function(){!o.paused&&r.hidden&&!a.querySelector(":focus-visible")&&(s.classList.add("is-idle"),f())},2600)}function M(){clearTimeout(v),h(),s.classList.add("is-idle"),f()}function h(){r.hidden=!0,d.setAttribute("aria-expanded","false")}function F(){var t=b(),n=t.filter(function(e){return e.mode==="showing"})[0];r.innerHTML="",[null].concat(t).forEach(function(s){var o=document.createElement("button");o.type="button",o.setAttribute("role","menuitemradio"),o.setAttribute("aria-checked",String(s?s===n:!n)),o.textContent=s?s.label||s.language:e[5],o.addEventListener("click",function(){t.forEach(function(e){e.mode=e===s?"showing":"disabled"}),h(),setTimeout(m,0),l()}),r.appendChild(o)}),r.hidden=!1,d.setAttribute("aria-expanded","true")}function x(){var n=!o.paused&&!o.ended;s.classList.toggle("is-playing",n),j.innerHTML=t(n?"pause":"play"),j.setAttribute("aria-label",n?e[1]:e[0]),n||l()}function S(){if(w.textContent=n(o.currentTime),!g&&o.duration){var e=o.currentTime/o.duration*1e3;c.value=e,c.style.setProperty("--p",e/10+"%")}}A.addEventListener("click",function(){o.play().catch(function(){})}),C="mouse",s.addEventListener("pointerdown",function(e){C=e.pointerType}),o.addEventListener("click",function(){if(!s.classList.contains("is-started"))return o.play().catch(function(){});if(C==="mouse")return y();s.classList.contains("is-idle")?l():M()}),j.addEventListener("click",y),o.addEventListener("play",function(){s.classList.contains("is-started")||i("film_play",o),s.classList.add("is-started"),x(),l()}),"IntersectionObserver"in window&&(E=new IntersectionObserver(function(e){if(!e.some(function(e){return e.isIntersecting}))return;E.disconnect(),i("film_view",o)},{threshold:.5}),E.observe(s)),o.addEventListener("pause",x),o.addEventListener("ended",x),o.addEventListener("timeupdate",S),o.addEventListener("durationchange",function(){O.textContent=n(o.duration),S()}),o.addEventListener("loadedmetadata",function(){O.textContent=n(o.duration)}),o.addEventListener("volumechange",function(){p.innerHTML=t(o.muted?"muted":"volume"),p.setAttribute("aria-label",o.muted?e[3]:e[2])}),p.addEventListener("click",function(){o.muted=!o.muted}),c.addEventListener("input",function(){g=!0,c.style.setProperty("--p",c.value/10+"%"),o.duration&&(o.currentTime=c.value/1e3*o.duration,w.textContent=n(o.currentTime))}),c.addEventListener("change",function(){g=!1}),d.addEventListener("click",function(e){e.stopPropagation(),r.hidden?F():h()}),document.addEventListener("click",function(e){!r.hidden&&!r.contains(e.target)&&h()}),u.addEventListener("click",function(){document.fullscreenElement||document.webkitFullscreenElement?(document.exitFullscreen||document.webkitExitFullscreen).call(document):s.requestFullscreen?s.requestFullscreen().catch(function(){}):s.webkitRequestFullscreen?s.webkitRequestFullscreen():o.webkitEnterFullscreen&&o.webkitEnterFullscreen()}),k=function(){var n=(document.fullscreenElement||document.webkitFullscreenElement)===s;s.classList.toggle("is-fullscreen",n),u.innerHTML=t(n?"exit":"full"),u.setAttribute("aria-label",n?e[7]:e[6])},document.addEventListener("fullscreenchange",k),document.addEventListener("webkitfullscreenchange",k),s.addEventListener("pointermove",function(e){e.pointerType==="mouse"&&l()}),s.addEventListener("focusin",l),s.addEventListener("keydown",function(e){if(e.target===c&&/^Arrow/.test(e.key))return;var t=e.key.toLowerCase();if(t==="k"||t===" "&&e.target===o)y();else if(t==="arrowleft")o.currentTime=Math.max(0,o.currentTime-5);else if(t==="arrowright")o.currentTime=Math.min(o.duration||0,o.currentTime+5);else if(t==="m")o.muted=!o.muted;else if(t==="f")u.click();else if(t==="escape"&&!r.hidden)h();else return;e.preventDefault(),l()}),o.tabIndex=0}window.mcFilm=function(){document.querySelectorAll(".mc-film:not(.is-ready)").forEach(c)},window.mcFilm()})()</script></div>
  <script>
  new MutationObserver(() => {
    const dark = document.documentElement.classList.contains("dark");
    document.querySelectorAll(".film-pair").forEach((pair) => {
      const from = pair.querySelector(dark ? ".film-light video" : ".film-dark video");
      const to = pair.querySelector(dark ? ".film-dark video" : ".film-light video");
      if (!from || !to || !from.currentTime) return;
      const playing = !from.paused;
      from.pause();
      to.currentTime = from.currentTime;
      [...from.textTracks].forEach((track, i) => { if (to.textTracks[i]) to.textTracks[i].mode = track.mode; });
      if (playing) to.play().catch(() => {});
    });
  }).observe(document.documentElement, { attributes: true, attributeFilter: ["class"] });
  </script><figcaption>这篇文章的八分钟视频版。旁白是英文，配有中文字幕。部分视频素材来自 Coverr。</figcaption>
</figure>


<h4 class="relative group">我为什么坚持做这件事
    <div id="我为什么坚持做这件事" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e4%b8%ba%e4%bb%80%e4%b9%88%e5%9d%9a%e6%8c%81%e5%81%9a%e8%bf%99%e4%bb%b6%e4%ba%8b" aria-label="锚点">#</a>
    </span>
    
</h4>
<p>我已经不把这些聊天当成招聘了。它们就是聊天，只是每隔一阵子，其中一场会变成一次入职——有时是十八个月之后，对方的处境变了。能稳定产出好员工的管道，是靠这样的关系一点点垒起来的，不是靠职位广告。</p>
<p>它还解决了职位描述的老问题。JD 天生只能写得笼统。喝着咖啡，候选人可以问真正要紧的问题：头六个月做到什么算成功？我会和谁一起工作？团队眼下最棘手的技术难题是什么？听到诚实回答的人，会自己做出正确的取舍。</p>
<p>另外，聊天是在“演示”你的文化，而不是“描述”它。你有没有做功课、是不是真的好奇、尊不尊重对方的时间，这些比任何招聘页面都有说服力。反过来也一样——一个人在放松的对话里的样子，比排练过的面试更能告诉你和他共事是什么感觉。</p>
<p>咖啡聊天最见效的几个场景：接触没在找工作的人；在正式流程之前给内推热热身；以及和正在考虑职业转向的人聊聊——从 IC（个人贡献者）转管理、从创业公司去大厂，或者反过来。在人才紧张的市场里，你想要的人多半都属于其中一类。</p>

<h4 class="relative group">我怎么安排一场咖啡聊天
    <div id="我怎么安排一场咖啡聊天" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%88%91%e6%80%8e%e4%b9%88%e5%ae%89%e6%8e%92%e4%b8%80%e5%9c%ba%e5%92%96%e5%95%a1%e8%81%8a%e5%a4%a9" aria-label="锚点">#</a>
    </span>
    
</h4>
<p>第一条消息决定一切。模板化的开场白只会被删掉。先做功课，再坦白来意：</p>
<p><em>“你好 Sarah，我看了你在 QCon 上关于分布式系统的演讲，也读过你写事件溯源的博客。我们在 [公司] 扩展支付基础设施时正遇到类似的挑战。愿不愿意来一场 30 分钟的咖啡聊天？没有面试议程——只是想听听你的看法，也分享一下我们在做的事。”</em></p>
<p>这样写有效，是因为它具体、不藏目的，而且给出了价值（一次关于有趣问题的交流），而不是单方面索取时间。接下来是把麻烦留给自己：多给几个时间选项，选对方方便的地点（线上就用不需要下载的视频工具），发一封信息完整的日历邀请，别让对方猜。</p>
<p>聊天本身有个松散的形状就够了。开头几分钟是真诚的寒暄，说清楚为什么找对方。然后听对方讲：现在的工作、喜欢什么、烦什么、下一步想要什么——这一段你的任务主要是听。再讲你们的事：使命、团队真实的难题，包括难啃的部分，因为候选人尊重坦诚，而且对推销的味道极其敏感。最有价值的是接近尾声的开放环节：什么条件成立，对方才会考虑挪动？最后把下一步说清楚，哪怕下一步只是“保持联系”。</p>
<p>聊完 24 小时内发一条简短的感谢，提到对话里某个具体细节；答应过的东西——引荐也好、链接也好——尽快兑现。这段无聊的收尾，才是公司文化的现场演示。</p>
<p>如果你打算长期做，就用一个简单的表格记下聊过的人，隔段时间问候一下，哪怕手上没有空缺。这也不必是管理者的专利——很多最好的聊天，发生在你的工程师约自己圈子里厉害的人喝咖啡的时候。好的内推往往就是这么来的。</p>

<h4 class="relative group">值得一问的问题
    <div id="值得一问的问题" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%80%bc%e5%be%97%e4%b8%80%e9%97%ae%e7%9a%84%e9%97%ae%e9%a2%98" aria-label="锚点">#</a>
    </span>
    
</h4>
<p>我常问的：</p>
<ul>
<li>“你最近做过的最有意思的问题是什么？”</li>
<li>“下一份工作里，你希望有什么不一样？”</li>
<li>“你喜欢怎样学习？希望怎样在职业上成长？”</li>
<li>“有什么问题是你想问的、能帮你判断这里合不合适的？”</li>
</ul>
<p>如果我坐在候选人那一侧，我会问：</p>
<ul>
<li>“团队现在面临的最大挑战是什么？”</li>
<li>“这个职位的成功怎么衡量？”</li>
<li>“晋升路径是什么样的？”</li>
<li>“你当初为什么加入？为什么留下来？”</li>
<li>“关于在这里工作，有什么事是会让我意外的？”</li>
</ul>

<h4 class="relative group">如果你是被邀请的那一方
    <div id="如果你是被邀请的那一方" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%a6%82%e6%9e%9c%e4%bd%a0%e6%98%af%e8%a2%ab%e9%82%80%e8%af%b7%e7%9a%84%e9%82%a3%e4%b8%80%e6%96%b9" aria-label="锚点">#</a>
    </span>
    
</h4>
<p>搜“咖啡聊天是什么”的人，大多其实坐在我对面：有人约了他们，他们想知道自己要面对的是什么。下面是我站在发邀请这一侧，想告诉你的话。</p>
<p>它不是面试。没人给你打分，也没有测试，所以不用准备标准答案。但它终究是第一印象，所以把它当成见一位未来的同事，而不是朋友的朋友。和面试不同的是，你可以尽管好奇，而且对方期待你问的和答的一样多。</p>
<p>穿你平时在那家公司上班会穿的衣服。拿不准的话，商务休闲永远不会错。如果是视频通话，打开摄像头，找个安静的房间，这比穿哪件衬衫重要得多。</p>
<p>准备大约半小时就够了。看看这家公司做什么，以及对方写过或做过的东西。准备一个两分钟的版本，讲讲你现在在做什么、接下来想做什么，因为这个问题一定会来。再带上两三个自己的问题，上面那份清单就是个不错的起点。</p>
<p>至于聊什么：你的工作、你喜欢它哪里、你对他们的工作好奇什么。薪资先放一放，除非对方主动提起。问一句他们心里有没有具体的职位、如果有的话流程会是怎样，完全没问题。</p>
<p>一般是发起邀请的人买单。你可以主动提一下，但别为这个推来推去。一天之内发一条简短的感谢，提到你们真正聊过的某件事，你就已经比大多数人做得好了。</p>
<p>如果你自己也想约一场，那就开口。消息写短一点，说清楚为什么找的是这个人，让对方容易答应：“我一直在关注你们团队做的新搜索功能，我自己也在考虑转去做平台工程。接下来几周你有没有 30 分钟，喝杯咖啡或者打个电话？时间按你方便来。”这么具体的请求，大多数人都会答应。</p>

<h4 class="relative group">把它搞砸的几种方法
    <div id="把它搞砸的几种方法" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%8a%8a%e5%ae%83%e6%90%9e%e7%a0%b8%e7%9a%84%e5%87%a0%e7%a7%8d%e6%96%b9%e6%b3%95" aria-label="锚点">#</a>
    </span>
    
</h4>
<p>最快的一种是把它变成暗中面试。一旦开始考察技术能力、往里塞行为面试题，那份默契就破了——这些留给正式流程。其次是用力过猛地推销：留得住的员工，都是把难处看清楚之后才加入的人。毫无准备地出现，或者聊完就消失，伤害更隐蔽——每一场聊天都在决定这个人会怎么向自己的圈子描述你的公司。</p>
<p>站在我这一侧，警报信号是：对什么都没有好奇心的候选人，纯粹交易感的对话，以及用同一种怨气描述每一任前雇主的人。候选人也该有自己的清单：说不清这份工作为什么重要的对接人，谈到流失率或公司方向就闪烁其词的回答，还有那种比起理解你更热衷于推销的人。</p>
<p>不是每场咖啡聊天都有下文，事实上大多数没有，这没关系。关键在于，下次要填一个重要岗位时，你不是从一页空白的招聘启事开始，而是从一摞真实的对话开始。发出去的应该是一句“喝杯咖啡吗”，而不是一份职位描述。</p>

<h4 class="relative group">延伸阅读
    <div id="延伸阅读" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%bb%b6%e4%bc%b8%e9%98%85%e8%af%bb" aria-label="锚点">#</a>
    </span>
    
</h4>
<p><strong>本站相关文章：</strong></p>
<ul>
<li><a href="https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-12-19-star-interviews/" >开发者面试中的 STAR 方法</a> —— 聊天进入正式面试流程后用得上</li>
<li><a href="https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-02-10-prioritizing-onboarding/" >刚当上工程经理，我先做这三件事</a> —— 团队靠什么运转，正是你在匹配的东西</li>
<li><a href="https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-07-01-internships/" >为什么你应该去创业公司实习</a> —— 和考虑去创业公司的人聊天时的有用背景</li>
</ul>
<p><strong>外部资源：</strong></p>
<ul>
<li><a href="https://review.firstround.com/articles/hiring-engineers/"  target="_blank" rel="noreferrer">First Round Review：工程师招聘</a> —— 经验丰富的创业公司操盘手写的招聘指南</li>
<li><a href="https://larahogan.me/blog/first-one-on-one-questions/"  target="_blank" rel="noreferrer">Lara Hogan 的“第一次 1:1 该问的问题”</a> —— 本是为 1:1 写的，用在咖啡聊天里同样好使</li>
<li><a href="https://www.kalzumeus.com/2012/01/23/salary-negotiation/"  target="_blank" rel="noreferrer">Patrick McKenzie 谈薪资谈判</a> —— 值得一读，帮你理解候选人那一侧的处境</li>
<li><a href="https://whothebook.com/" target="_blank" rel="noreferrer">Who: The A Method for Hiring</a> —— Geoff Smart 和 Randy Street 的系统化招聘框架</li>
<li><a href="https://hbr.org/topic/subject/hiring-and-recruitment"  target="_blank" rel="noreferrer">哈佛商业评论：招聘专题</a> —— 有研究支撑的人才招募文章</li>
</ul>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2024/2024-07-12-coffee-chats/featured.jpg" medium="image" type="image/jpeg" />
    </item>
    <item>
      <title>Orval：从OpenAPI规范自动生成带类型的API客户端和mock</title>
      <link>https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-04-10-openapitools/</link>
      <guid isPermaLink="true">https://jared.lynskey.co.nz/zh-cn/posts/2024/2024-04-10-openapitools/</guid>
      <pubDate>Wed, 10 Apr 2024 00:30:03 +0000</pubDate>
      <dc:creator>Me</dc:creator>
      <category>API Development</category>
      <category>Orval</category>
      <category>OpenAPI</category>
      <category>TypeScript</category>
      <category>React Query</category>
      <category>MSW</category>
      <category>Frontend</category>
      <category>Backend</category>
      <category>Teamwork</category>
      <category>Efficiency</category>
      <description>Orval读取OpenAPI规范，生成带类型的TypeScript客户端、React Query hooks和MSW mock，没人需要再手写API层。本文讲怎么配置、mock怎么用，以及它和openapi-generator、openapi-typescript、Hey API比起来怎么样。</description>
      <content:encoded><![CDATA[<p>Orval是一个代码生成器：它读取OpenAPI（Swagger）规范，替你写好前端的API层。每个接口一个带类型的函数或React Query hook，TypeScript模型和契约完全一致，需要的话还有填好Faker数据的MSW mock handler。你只要提交一个配置文件，运行<code>orval</code>，规范一变就再运行一次。</p>
<p>这个系列的第一篇里，我主张在写任何代码之前先把OpenAPI契约定下来。这一篇要讲的，是让这份契约真正“回本”的工具。</p>
<p>手写前端的API层，是那种没人会承认自己喜欢的活儿。从后端文档里抄类型，第四十次写同一个请求封装，三周后有人把某个字段改了名，一半的调用就悄无声息地坏掉了。Orval直接把这个活儿删掉了。把它指向你的OpenAPI规范，客户端代码就自动生成：每个接口都有带类型的函数，模型和契约完全一致，还有后端根本不存在时就能用来开发的mock。</p>

<h2 class="relative group">前端团队为什么喜欢它
    <div id="前端团队为什么喜欢它" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%89%8d%e7%ab%af%e5%9b%a2%e9%98%9f%e4%b8%ba%e4%bb%80%e4%b9%88%e5%96%9c%e6%ac%a2%e5%ae%83" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>mock生成是最被低估的部分。规范一旦谈定，前端就能起一个假服务器，对着它把整个UI做完，不用再等那些永远“快好了”的接口。等真正的后端上线，把客户端指过去，大部分东西直接就能跑，因为两边是照着同一份文档做的。</p>
<p>另一个收获是：无聊的代码从此“天生正确”。没有人会在手写的请求体里敲错字段名了，因为根本没有人再手写请求体。</p>

<h2 class="relative group">后端团队为什么也喜欢它
    <div id="后端团队为什么也喜欢它" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%90%8e%e7%ab%af%e5%9b%a2%e9%98%9f%e4%b8%ba%e4%bb%80%e4%b9%88%e4%b9%9f%e5%96%9c%e6%ac%a2%e5%ae%83" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>规范成为唯一事实来源之后，日常沟通都变了。不再有“这个接口到底返回什么来着？”的群聊追问，前端直接看生成的类型就行。后端开发者被打断得更少，反馈来得更早：前端对着mock开发时觉得哪个API别扭，你在改起来还便宜的阶段就知道了，而不是等它进了生产环境。</p>

<h2 class="relative group">怎么融入工作流
    <div id="怎么融入工作流" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e6%80%8e%e4%b9%88%e8%9e%8d%e5%85%a5%e5%b7%a5%e4%bd%9c%e6%b5%81" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>没什么花哨的。后端提出规范，两个团队一起评审；前端用Orval生成客户端和mock，直接开工；后端按同一份契约实现真实接口。规范一变，两边重新生成，编译器会准确告诉你哪里坏了。最后这一点才是全部意义所在：前后端之间的偏差，从生产事故变成了编译错误。</p>

<h2 class="relative group">配置
    <div id="配置" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e9%85%8d%e7%bd%ae" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>先把它装成开发依赖，再装上生成的代码要import的那些包。要生成React Query hooks和mock的话，就是TanStack Query、MSW和Faker：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">npm install --save-dev orval msw @faker-js/faker
</span></span><span class="line"><span class="cl">npm install @tanstack/react-query</span></span></code></pre></div></div>
<p>然后在项目根目录加一个<code>orval.config.ts</code>。下面这份和Orval官方文档里的示例很接近：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-ts" data-lang="ts"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">defineConfig</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;orval&#39;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">export</span> <span class="k">default</span> <span class="nx">defineConfig</span><span class="p">({</span>
</span></span><span class="line"><span class="cl">  <span class="nx">petstore</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nx">input</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">target</span><span class="o">:</span> <span class="s1">&#39;./openapi.yaml&#39;</span><span class="p">,</span> <span class="c1">// a path or a URL
</span></span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="nx">output</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">      <span class="nx">mode</span><span class="o">:</span> <span class="s1">&#39;single&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">target</span><span class="o">:</span> <span class="s1">&#39;./src/api/petstore.ts&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">schemas</span><span class="o">:</span> <span class="s1">&#39;./src/api/model&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">client</span><span class="o">:</span> <span class="s1">&#39;react-query&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">httpClient</span><span class="o">:</span> <span class="s1">&#39;fetch&#39;</span><span class="p">,</span>
</span></span><span class="line"><span class="cl">      <span class="nx">mock</span>: <span class="kt">true</span><span class="p">,</span> <span class="c1">// MSW handlers plus Faker data
</span></span></span><span class="line"><span class="cl">      <span class="nx">override</span><span class="o">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">        <span class="nx">fetch</span><span class="o">:</span> <span class="p">{</span> <span class="nx">includeHttpResponseReturnType</span>: <span class="kt">false</span> <span class="p">},</span>
</span></span><span class="line"><span class="cl">      <span class="p">},</span>
</span></span><span class="line"><span class="cl">    <span class="p">},</span>
</span></span><span class="line"><span class="cl">  <span class="p">},</span>
</span></span><span class="line"><span class="cl"><span class="p">});</span></span></span></code></pre></div></div>
<p><code>client</code>决定你拿到什么：普通的<code>fetch</code>或<code>axios</code>函数，React Query、Vue Query、Svelte Query或SWR的hooks，Angular service，或者Zod schema。<code>includeHttpResponseReturnType: false</code>这一行让fetch客户端直接返回响应体，而不是<code>{ data, status }</code>，组件要的通常就是这个。</p>
<p>再加一条script，省得每个人都得记命令：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-json" data-lang="json"><span class="line"><span class="cl"><span class="p">{</span>
</span></span><span class="line"><span class="cl">  <span class="nt">&#34;scripts&#34;</span><span class="p">:</span> <span class="p">{</span>
</span></span><span class="line"><span class="cl">    <span class="nt">&#34;api&#34;</span><span class="p">:</span> <span class="s2">&#34;orval&#34;</span>
</span></span><span class="line"><span class="cl">  <span class="p">}</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p><code>npm run api</code>会生成hooks和模型。组件里用起来和别的React Query hook没什么两样，类型都已经填好了：</p>
<div class="highlight-wrapper"><div class="highlight"><pre tabindex="0" class="chroma"><code class="language-tsx" data-lang="tsx"><span class="line"><span class="cl"><span class="kr">import</span> <span class="p">{</span> <span class="nx">useListPets</span> <span class="p">}</span> <span class="kr">from</span> <span class="s1">&#39;./api/petstore&#39;</span><span class="p">;</span>
</span></span><span class="line"><span class="cl">
</span></span><span class="line"><span class="cl"><span class="kr">export</span> <span class="kd">function</span> <span class="nx">PetList() {</span>
</span></span><span class="line"><span class="cl">  <span class="kr">const</span> <span class="p">{</span> <span class="nx">data</span>: <span class="kt">pets</span><span class="p">,</span> <span class="nx">isLoading</span> <span class="p">}</span> <span class="o">=</span> <span class="nx">useListPets</span><span class="p">();</span>
</span></span><span class="line"><span class="cl">  <span class="k">if</span> <span class="p">(</span><span class="nx">isLoading</span><span class="p">)</span> <span class="k">return</span> <span class="p">&lt;</span><span class="nt">p</span><span class="p">&gt;</span><span class="nx">Loading</span><span class="err">…</span><span class="p">&lt;/</span><span class="nt">p</span><span class="p">&gt;;</span>
</span></span><span class="line"><span class="cl">  <span class="k">return</span> <span class="p">(</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;</span><span class="nt">ul</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">      <span class="p">{</span><span class="nx">pets</span><span class="o">?</span><span class="p">.</span><span class="nx">map</span><span class="p">((</span><span class="nx">pet</span><span class="p">)</span> <span class="o">=&gt;</span> <span class="p">&lt;</span><span class="nt">li</span> <span class="na">key</span><span class="o">=</span><span class="p">{</span><span class="nx">pet</span><span class="p">.</span><span class="nx">id</span><span class="p">}&gt;{</span><span class="nx">pet</span><span class="p">.</span><span class="nx">name</span><span class="p">}&lt;/</span><span class="nt">li</span><span class="p">&gt;)}</span>
</span></span><span class="line"><span class="cl">    <span class="p">&lt;/</span><span class="nt">ul</span><span class="p">&gt;</span>
</span></span><span class="line"><span class="cl">  <span class="p">);</span>
</span></span><span class="line"><span class="cl"><span class="p">}</span></span></span></code></pre></div></div>
<p>在规范里给某个字段改个名，再跑一次<code>npm run api</code>，所有用到<code>pet.name</code>的地方都会变红。这就是上面说的偏差检查，而且跑一次不花任何成本。</p>

<h2 class="relative group">对着mock开发
    <div id="对着mock开发" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#%e5%af%b9%e7%9d%80mock%e5%bc%80%e5%8f%91" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>开了<code>mock: true</code>之后，Orval还会为每个接口生成一个MSW请求handler，返回按响应结构填充的Faker数据，外加一个把所有handler一次性返回的函数。把这份列表交给浏览器里MSW的<code>setupWorker</code>，或者测试里的<code>setupServer</code>，应用就跑在一个已经符合契约的假后端上了。每个handler还能传入覆盖值，测试想返回特定的payload、空列表或错误状态都行，不用有人手写fixture。</p>
<p>前端能从第一天就开工，靠的就是这一点。mock不是另一份需要有人维护的产物：它和客户端从同一份规范重新生成，所以不可能落后于规范。</p>

<h2 class="relative group">Orval vs openapi-generator、openapi-typescript和Hey API
    <div id="orval-vs-openapi-generatoropenapi-typescript和hey-api" class="anchor"></div>
    
    <span
        class="absolute top-0 w-6 transition-opacity opacity-0 -start-6 not-prose group-hover:opacity-100 select-none">
        <a class="text-primary-300 dark:text-neutral-700 !no-underline" href="#orval-vs-openapi-generatoropenapi-typescript%e5%92%8chey-api" aria-label="锚点">#</a>
    </span>
    
</h2>
<p>它们都从OpenAPI规范出发，只是走到的地方不一样。</p>
<table>
	<thead>
			<tr>
					<th></th>
					<th>生成什么</th>
					<th>最适合</th>
			</tr>
	</thead>
	<tbody>
			<tr>
					<td><strong>Orval</strong></td>
					<td>带类型的客户端函数或框架hooks（React Query、SWR、Vue、Svelte、Angular）、模型、MSW mock、Zod schema</td>
					<td>想用一份配置同时拿到hooks和mock的TypeScript前端</td>
			</tr>
			<tr>
					<td><strong>openapi-generator</strong></td>
					<td>几十种语言的客户端和服务端桩代码，包括TypeScript</td>
					<td>需要把同一份规范转成Java、Kotlin、Swift和TypeScript的团队</td>
			</tr>
			<tr>
					<td><strong>openapi-typescript</strong></td>
					<td>只生成类型，配合<code>openapi-fetch</code>得到一个轻量的带类型fetch封装</td>
					<td>只要类型，几乎不想要运行时代码</td>
			</tr>
			<tr>
					<td><strong>Hey API</strong>（<code>@hey-api/openapi-ts</code>）</td>
					<td>带类型的SDK，有TanStack Query、Zod等插件</td>
					<td>和Orval定位相近，围绕插件系统构建</td>
			</tr>
	</tbody>
</table>
<p>如果只需要类型，openapi-typescript最轻，很难挑出毛病。openapi-generator的用武之地，是规范要喂给不止一种语言的时候；它的TypeScript输出能用，但读起来像是先为Java写的。Orval和Hey API之间，基本就看口味，以及你更愿意读哪一家生成的代码。我一直用Orval，是因为mock和hooks出自同一次运行，而正是这一点改变了两个团队的协作方式。</p>
<p>这不是什么光鲜的工具。它只是安安静静地消灭了团队之间一整类争吵，这笔买卖我每次都愿意做。</p>
]]></content:encoded>
      <media:content url="https://jared.lynskey.co.nz/en/posts/2024/2024-04-10-openapitools/featured.jpg" medium="image" type="image/jpeg" />
    </item>
  </channel>
</rss>
