Markdown 渲染压测 v1

目标：把常见/罕见语法全打一遍，观察终端渲染器的降级行为。 约束：不落盘，全部在本条消息里。

0. 目录（锚点/链接测试）

• 1. 标题层级
• 2. 行内样式
• 3. 列表全家桶
• 4. 表格
• 5. 代码
• 6. 引用
• 7. 图片与 SVG
• 8. 数学公式
• 9. 图表
• 10. HTML 内联
• 11. 边界与变态用例

1. 标题层级

H1 一级标题

H2 二级标题

H3 三级标题

H4 四级标题

H5 五级标题

H6 六级标题

Setext H1

Setext H2

2. 行内样式

粗体、斜体、粗斜体、删除线、行内代码、粗体里嵌 代码、斜体里嵌 粗体。

下划线（HTML）：带下划线的文字 高亮：高亮文本 上标：E = mc²，xⁿ 下标：H₂O，a_i 键盘：按 ⌘ + Shift + P 打开命令面板 缩写：API 小字：这是 small 标签

转义测试：*不是斜体* `不是代码` # 不是标题 [不是链接]

硬换行（行尾两空格）：
第二行，应该紧贴上一行但换行。

反斜杠换行：
同样换行。

3. 列表全家桶

无序：

• 苹果
• 香蕉
  • 芭蕉
  • 大蕉
    • 更深一层
• 樱桃

有序：

1. 第一步
2. 第二步
   1. 子步骤 2.1
   2. 子步骤 2.2
3. 第三步

有序（非 1 起始）：

7. 从 7 开始
8. 然后是 8
9. 然后是 9

混合嵌套：

1. 外层有序
   • 中层无序
     1. 内层有序
        • 最内层无序 code
2. 回到外层

任务列表：

• 已完成项
• 未完成项
• 带 代码 的完成项
  • 嵌套未完成
  • 嵌套已完成

定义列表（非 GFM，测降级）：

术语 A : 术语 A 的定义说明。

术语 B : 术语 B 的第一条定义。 : 术语 B 的第二条定义。

松散列表（项间空行）：

• 第一段

• 第二段

• 第三段

列表项内多段：

• 项目开头

  缩进的第二段，属于同一个列表项。

  // 列表项里的代码块
  const x = 1;
  

• 下一个项目

4. 表格

基础表：

对齐表：

宽表（测横向滚动 / 截断）：

表格内转义竖线：

表格内换行（HTML <br>）：

空单元格与不齐整的列：

5. 代码

行内：npm run build、Array.prototype.map、<div class="x">、a || b、$PATH。

缩进式代码块：

function legacy() {
  return "indented code block";
}

围栏（无语言）：

plain text, no highlight
  保留    空格
	Tab 缩进

JavaScript：

// 注释：计算斐波那契
const fib = (n, memo = new Map()) => {
  if (n < 2) return n;
  if (memo.has(n)) return memo.get(n);
  const v = fib(n - 1, memo) + fib(n - 2, memo);
  memo.set(n, v);
  return v;
};

class Counter {
  #count = 0;                    // 私有字段
  static ORIGIN = "0x00";
  get value() { return this.#count; }
  increment(by = 1) { this.#count += by; return this; }
}

console.log(`fib(40) = ${fib(40)}`);
export default Counter;

TypeScript：

interface User<T extends string = string> {
  id: number;
  name: T;
  roles: ReadonlyArray<"admin" | "user">;
  meta?: Record<string, unknown>;
}

type Result<T, E = Error> =
  | { ok: true; value: T }
  | { ok: false; error: E };

async function fetchUser(id: number): Promise<Result<User>> {
  try {
    const res = await fetch(`/api/users/${id}`);
    return { ok: true, value: (await res.json()) as User };
  } catch (error) {
    return { ok: false, error: error as Error };
  }
}

Python：

from dataclasses import dataclass, field
from typing import Iterator

@dataclass(slots=True)
class Point:
    x: float
    y: float
    tags: list[str] = field(default_factory=list)

    def __iter__(self) -> Iterator[float]:
        yield self.x
        yield self.y

def primes(limit: int) -> list[int]:
    """埃拉托斯特尼筛法"""
    sieve = bytearray([1]) * (limit + 1)
    sieve[0:2] = b"\x00\x00"
    for i in range(2, int(limit ** 0.5) + 1):
        if sieve[i]:
            sieve[i * i :: i] = bytearray(len(sieve[i * i :: i]))
    return [i for i, ok in enumerate(sieve) if ok]

if __name__ == "__main__":
    print(f"{len(primes(1_000_000))} primes below 1e6")

Bash：

#!/usr/bin/env bash
set -euo pipefail

readonly ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
trap 'echo "failed at line $LINENO" >&2' ERR

for f in "$ROOT"/src/**/*.ts; do
  [[ -f "$f" ]] || continue
  printf '%s\t%s\n' "$(wc -l < "$f")" "${f##*/}"
done | sort -rn | head -n 10

Go：

package main

import (
	"context"
	"errors"
	"fmt"
	"time"
)

var ErrTimeout = errors.New("timeout")

func worker(ctx context.Context, jobs <-chan int, out chan<- int) error {
	for {
		select {
		case <-ctx.Done():
			return ctx.Err()
		case j, ok := <-jobs:
			if !ok {
				return nil
			}
			select {
			case out <- j * j:
			case <-time.After(100 * time.Millisecond):
				return fmt.Errorf("job %d: %w", j, ErrTimeout)
			}
		}
	}
}

Rust：

use std::collections::HashMap;

#[derive(Debug, Clone, PartialEq)]
enum Shape { Circle(f64), Rect { w: f64, h: f64 } }

impl Shape {
    fn area(&self) -> f64 {
        match self {
            Shape::Circle(r) => std::f64::consts::PI * r * r,
            Shape::Rect { w, h } => w * h,
        }
    }
}

fn main() {
    let shapes = vec![Shape::Circle(1.0), Shape::Rect { w: 3.0, h: 4.0 }];
    let total: f64 = shapes.iter().map(Shape::area).sum();
    println!("total = {total:.3}");
}

SQL：

WITH ranked AS (
  SELECT
    user_id,
    order_id,
    amount,
    ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY created_at DESC) AS rn
  FROM orders
  WHERE created_at >= NOW() - INTERVAL '30 days'
)
SELECT u.name, r.order_id, r.amount
FROM ranked r
JOIN users u ON u.id = r.user_id
WHERE r.rn = 1
ORDER BY r.amount DESC
LIMIT 10;

JSON / YAML / TOML：

{
  "name": "acme",
  "version": "2.4.1",
  "deps": { "react": "^19.0.0" },
  "scripts": { "build": "tsc -b && vite build" },
  "keywords": ["log", "cli", "分析"],
  "private": true
}

apiVersion: apps/v1
kind: Deployment
metadata:
  name: acme-api
  labels: { app: acme, tier: backend }
spec:
  replicas: 3
  template:
    spec:
      containers:
        - name: api
          image: registry.example.com/acme:2.4.1
          resources:
            limits: { cpu: "1", memory: 512Mi }
          env:
            - name: LOG_LEVEL
              value: "info"

[package]
name = "acme"
version = "2.4.1"
edition = "2021"

[dependencies]
serde = { version = "1", features = ["derive"] }

[profile.release]
lto = true

Diff：

--- a/src/parser.rs
+++ b/src/parser.rs
@@ -12,7 +12,9 @@ impl Parser {
-    pub fn parse(&self, s: &str) -> Option<Ast> {
-        self.inner(s).ok()
+    pub fn parse(&self, s: &str) -> Result<Ast, ParseError> {
+        self.inner(s).map_err(|e| e.with_span(self.span(s)))
     }
 }

超长行（测横向滚动 / 自动换行）：

const veryLongLine = ["alpha","bravo","charlie","delta","echo","foxtrot","golf","hotel","india","juliet","kilo","lima","mike","november","oscar","papa","quebec","romeo","sierra","tango","uniform","victor","whiskey","xray","yankee","zulu"].map(x => x.toUpperCase()).filter(x => x.length > 4).join(" | ");

无语言但带标题/元信息的围栏：

2026-09-22T10:00:01Z INFO  server started on :8080
2026-09-22T10:00:02Z WARN  cache miss ratio 0.42
2026-09-22T10:00:03Z ERROR failed to connect to redis: dial tcp 10.0.0.7:6379: i/o timeout

四反引号围栏（内含三反引号）：

```js
console.log("嵌套围栏");
```

6. 引用

单层引用。 第二行，同一段。

引用里的 格式、代码、链接。

第一层

第二层

第三层

第四层，还能更深吗

引用里的标题

• 引用里的列表
• 第二项

// 引用里的代码块

A	B
1	2

[!NOTE] GFM 警报：提示信息。

[!TIP] GFM 警报：技巧。

[!IMPORTANT] GFM 警报：重要。

[!WARNING] GFM 警报：警告。

[!CAUTION] GFM 警报：危险。

引用 + 列表 + 代码混合：

1. 有序项

   项内引用

   更深引用

7. 图片与 SVG

7.1 远程图片（需要网络，可能不加载）

7.2 内联 SVG（原始 <svg> 标签，多数终端渲染器会忽略或原样显示）

7.3 SVG Data URI（base64）

7.4 SVG Data URI（utf8 未编码，测降级）


7.5 带 title 的图片

7.6 引用式图片 + 引用式链接

7.7 徽章（ shields.io 风格）

7.8 HTML <img> 带尺寸

7.9 ASCII 图（终极降级方案）

┌─────────────┐      ┌─────────────┐      ┌─────────────┐
│   Client    │─────▶│   Gateway   │─────▶│   Service   │
└─────────────┘      └──────┬──────┘      └──────┬──────┘
                            │                    │
                            ▼                    ▼
                     ┌─────────────┐      ┌─────────────┐
                     │    Redis    │      │  PostgreSQL │
                     └─────────────┘      └─────────────┘

8. 数学公式

行内：质能方程 E = mc²，以及 ∑_i=1ⁿ i = n(n+1)2。

块级：

∫_−∞^∞ e^−x2dx = √π

∇ ⋅ E= ρε₀∇ ⋅ B= 0∇ × E= −∂ B∂ t∇ × B= μ₀ J + μ₀ε₀ ∂ E∂ t

矩阵：

A = (a₁₁a₁₂a₂₁a₂₂),  det(A) = a₁₁a₂₂ − a₁₂a₂₁

非公式的美元符号（测误判）：这件商品 $9.99，那件 $19.99，一共 $29.98。

9. 图表

9.1 Mermaid 流程图

9.2 Mermaid 时序图

9.3 Mermaid 甘特图

9.4 Mermaid 类图

9.5 Mermaid 饼图 / 状态图

9.6 纯文本柱状图

Q1  ████████████░░░░░░░░  60%
Q2  ██████████████████░░  90%
Q3  ██████░░░░░░░░░░░░░░  30%
Q4  ████████████████████ 100%

10. HTML 内联

console.log("折叠里的代码");

HTML 表格：

HTML 注释（应完全不可见）：

其他标签：inline code via html、b、i、s、引用标签、引用来源、术语定义、2026年9月22日、漢かん字じ、进度条 、60%。

11. 边界与变态用例

11.1 超长不可断字符串（URL）

https://example.com/very/long/path/that/never/ends/and/keeps/going/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa?query=1&another=2

11.2 自动链接

裸链接：https://github.com/anthropics/claude-code 尖括号：https://github.com/anthropics/claude-code 邮箱：noreply@example.com 自定义文本：Claude Code 仓库

11.3 引用式链接

这是引用式链接，这是另一个，这是短形式。

11.4 脚注

这里有个论断¹，还有个补充说明²，以及一个长脚注³。

11.5 Emoji 与 Unicode

表情：😀 🎉 🚀 ✅ ❌ ⚠️ 🔥 💡 📊 🧪 🐛 短代码：:smile: :tada: :rocket: :white_check_mark: :x: ZWJ 序列：👨👩👧👦 👩💻 🧑🚀 🏳️🌈 肤色修饰：👍🏻 👍🏽 👍🏿 国旗：🇨🇳 🇺🇸 🇯🇵 🇩🇪 🇫🇷 符号：→ ← ↑ ↓ ⇒ ⇔ ∀ ∃ ∈ ∉ ⊂ ⊃ ∪ ∩ ∑ ∏ √ ∞ ≠ ≤ ≥ ± × ÷ ° µ Ω 框线：┌ ┐ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ║ ╔ ╗ ╚ ╝ 块元素：░ ▒ ▓ █ ▄ ▀ ▌ ▐ 中文标点：「引号」、『双引号』、《书名号》、——破折号……省略号。 全角：ＡＢＣ１２３，全角空格【　】。 零宽字符：a\u200Bb（中间有零宽空格） 组合字符：é（e + U+0301）、ñ（n + U+0303）、Ω（Ω + U+0301） 数学字母：𝔸𝔹ℂ 𝓪𝓫𝓬 𝐀𝐁𝐂 𝟏𝟐𝟑 罕见 CJK：龘靐齉爩鱻麤龗灪 RTL：مرحبا بالعالم / שלום עולם 混合 BiDi：这段是中文 English 123 العربية 混合排版。

11.6 超深嵌套列表（测缩进溢出）

• L1
  • L2
    • L3
      • L4
        • L5
          • L6
            • L7
              • L8
                • L9
                  • L10 到底了

11.7 连续分隔线变体

11.8 空元素与空白

行内空代码：“，空粗体：****，空链接：，空图片：。

11.9 特殊字符攻击（不应破坏渲染）

<script>alert(1)</script> 应该原样显示。 <img src=x onerror=alert(1)> 转义后应原样显示。

11.10 超长表格（50 行，测虚拟滚动/性能）

压测完成

以上全部在会话内输出，未写入任何文件。

结论

自己写中间件，不引库。按 IP 限流用令牌桶，计数放 Redis——网关是 3 副本，计数留在进程内存里等于把阈值放大三倍。

取 IP 有两个坑

1. 网关前面还有一层 LB，r.RemoteAddr 拿到的是 LB 的地址，得看 X-Forwarded-For；
2. X-Forwarded-For 是客户端可以伪造的，所以只信最后一跳：从右往左找第一个不在可信网段里的地址，找不到就退回 RemoteAddr。

中间件

func RateLimit(store *redis.Client, cfg LimitConfig) func(http.Handler) http.Handler {
	return func(next http.Handler) http.Handler {
		return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			key := "rl:ip:" + clientIP(r)
			ok, retryAfter := allow(r.Context(), store, key, cfg)
			if !ok {
				w.Header().Set("Retry-After", strconv.Itoa(int(retryAfter.Seconds())))
				http.Error(w, "rate limit exceeded", http.StatusTooManyRequests)
				return
			}
			next.ServeHTTP(w, r)
		})
	}
}

还没定的两件事

• 按 API key 分档：key 从 Authorization 头里取，桶容量走配置，与 IP 桶分开计数，别共用一个 key 前缀；
• 超限之后：现在只回 429，不带剩余额度。如果客户端是重试风暴，响应里最好带上 X-RateLimit-Remaining，让它自己退避。

Redis 用 EVALSHA 跑令牌桶，取桶与扣减在一次 Lua 里完成，否则两个副本同时读到「还剩 1 个」会一起放行。

定位

先打开 pg_stat_statements，按调用次数排前五：

select calls, round(total_exec_time) as ms, left(query, 60)
from pg_stat_statements order by calls desc limit 5;

select * from projects where owner_id = $1 调了 14208 次，而首屏一共只渲染 24 个项目——每个项目一条，N+1 坐实了。

修法

把循环里的单条查询换成一次 IN，再在内存里 join：

const ids = rows.map((r) => r.ownerId);
const owners = await db.query('select * from owners where id = any($1)', [ids]);
const byId = new Map(owners.map((o) => [o.id, o]));

一起改的三处

1. src/dashboard/load.ts 里的循环查询——改成批量取；
2. 同一份 owner 数据在三个组件里各查一次，用 DataLoader 在请求级做去重（按 id 缓存，别跨请求复用，否则会把 A 的数据发给 B）；
3. 加一条回归断言：单次渲染的 SQL 条数不超过 12 条，超了就失败。

改完首屏 4.2s → 0.6s，SQL 条数 240 → 9。剩下的 9 条里有 4 条是权限校验，可以缓存，先没动。

先盘一遍用到的地方

rg -o "moment\([^)]*\)\.\w+" src/ | sed 's/.*\.//' | sort | uniq -c

出来只有 6 种用法：格式化、加减天数、比较先后、取当月首日、时区转换、相对时间。没有用 locale 的复杂分支，替换面很小。

对照表

两个会静默出错的地方

1. 格式串的 token 大小写不一样：YYYY → yyyy、DD → dd。直接全局替换，DD（一年中的第几天）会顶掉 dd（几号），页面上不报错，日期就是错的；
2. moment 对象可变，date-fns 全是纯函数。const end = start.add(7, 'days') 这种写法在 moment 里改的是 start 本身，换成 addDays 后 start 不动了——如果原来的代码依赖这个副作用，行为会变。

时区那块先留着 moment-timezone 的两个调用，date-fns-tz 的 API 形状差得比较多，单独一个 PR 改。

建议的结构

现在的文档是「先讲清楚再动手」，新人读到第三步就断了。改成边做边读，四段就够：

1. 一句话说清它是干什么的——不要从架构讲起，架构留到第四段；
2. 跑起来——三条命令，复制粘贴就能看到结果，中间不解释原理；
3. 改一处再看结果——让读者第一次感受到反馈闭环，这一步比前面两步都重要；
4. 接下来去哪——把原来的架构说明拆成链接，想深入的人自己点。

第 2 段照这个写

git clone <repo> && cd <repo>
npm install
npm run dev   # 打开 http://localhost:4321

三条命令各自只配一句话说明「它做了什么」，不写「为什么要装依赖」这种读者此刻不关心的话。

第 3 段挑一个最小改动

选一个改完立刻看得见的：比如把首页标题改掉，刷新页面就能看到。不要一上来就让读者改配置或加路由，那种改动要么不生效、要么生效在别的地方，新人分不清是自己错了还是文档错了。

删掉的东西

• 开头那段「本指南适合谁」——读者已经在读了，不用再介绍一遍；
• 环境要求里列了 6 种包管理器，只留 npm 一种，其余放脚注；
• 截图全部换掉：现在的截图还是旧版界面，颜色和布局都对不上。

迁移复盘纪要（2 月 17 日）

结果：数据迁移完成，停机 42 分钟，比计划多 12 分钟。回滚预案没有启用。

做对了什么

• 提前一周做了全量演练，演练脚本与正式脚本是同一份，只换了目标库的连接串；
• 迁移前把写入流量切到只读，省掉了「迁移过程中新写入的数据对不上」这一类问题；
• 每一步都有校验点：行数、金额合计、最近 7 天的抽样比对，前一步不过就不走下一步。

踩了什么坑

1. 索引建晚了：数据灌完才建索引，多花了 12 分钟——应该在只读切换前就把索引建好，灌数据的同时索引一起长；
2. 连接池没调：迁移脚本用了应用的默认连接池（10 个），实际只有 2 个在干活，其余时间在等锁。单独给迁移脚本配 32 个连接能再快一截；
3. 监控看错了面板：值班同学盯着应用的错误率，没注意迁移脚本自己的进度指标，中途有一次「看起来卡住了」的误判。

下次怎么改

• 迁移脚本的索引与数据分开两步，索引提前建；
• 迁移期间单独开一个面板，只放进度、剩余行数、当前速率三个指标；
• 停机窗口按演练耗时的 1.5 倍申请，这次按 1.2 倍申请，实际差了 12 分钟。

遗留

旧的只读副本还没下线，先留一周做比对，下周三回收。

脚本

// scripts/digest.mjs
const { since, until, dryRun } = parseArgs(process.argv); // --since / --until，缺省是最近 7 天
const projects = await listProjects();

for (const p of projects) {
  const [done, blocked] = await Promise.all([
    issues({ project: p, state: 'closed', since, until }),
    issues({ project: p, label: 'blocked' }),
  ]);
  print(p.name, { done: done.length, blocked: blocked.map((i) => i.title) });
}
if (!dryRun) writeReport({ projects, since, until });

跑一次是 node scripts/digest.mjs --since <开始> --until <结束>，加 --dry-run 只打印不写文件；不传 --until 就是到今天为止。

定时的两种做法

• 系统定时任务：周五 16:00 跑一次，窗口取上周六到本周五，输出写到 reports/digest-<date>.md，简单但只在跑脚本的那台机器上生效；
• 交给调度器：同一份脚本包一层，失败会重试、有历史记录，代价是要维护一个调度任务。

先按第一种来，脚本本身不依赖运行环境，以后要换随时能换。

输出模板

固定三段，抓不到的部分留空行让人补：

1. 本周完成——按项目分组，每行一条 issue 标题；
2. 阻塞——带 blocked 标签的，写清楚卡在谁那里；
3. 下周计划——不自动生成，留给本人填。

模板固定下来之后，每周实际要动手的部分只剩第三段，这才是省时间的地方。

先看时间花在哪

本地跑一遍，把每个文件的耗时导出来：

npx vitest run --reporter=json --outputFile=timing.json
node scripts/slowest.mjs timing.json

一共 4 分 12 秒、1284 个用例，但最慢的 8 个文件就占了 61%——editor.test.ts 一个文件 58 秒。 这说明时间不是被「用例多」吃掉的，是被少数几个大文件吃掉的。

分片要按耗时切，不按文件数

按文件数均分是最容易踩的坑：4 片各 30 个文件，看着很公平，但最慢的那片还是带着 editor.test.ts， 整体时长由最慢的一片决定，省不下来。按累计耗时贪心装箱，4 片的预算是 63 秒 / 62 秒 / 61 秒 / 60 秒， 几乎齐平。

CI 侧用矩阵跑：

strategy:
  matrix:
    shard: [1, 2, 3, 4]
steps:
  - run: npx vitest run --shard=${{ matrix.shard }}/4

并行前必须先排掉共享状态

分片是在同一台机器上并发跑的，下面两处会互相踩，得先改：

1. src/test/setup.ts 里的临时目录写死在 /tmp/app-test，四个分片同时往里写；改成按分片号加后缀；
2. 有三个用例依赖同一个固定端口起本地服务，改成 listen(0) 让内核分配，再从 address() 取回实际端口。

改完跑了一遍并发压测（4 个分片同时跑 20 次），没有出现 flake。

结果

CI 从 22 分钟降到 7 分钟，其中装依赖与构建仍占 3 分钟——那部分靠分片省不了， 下一步如果还要压，得从缓存下手，那是另一件事。

现状

本地 v22.11.0，CI 用的是镜像默认的 v20.9.0，而仓库里一处都没声明过版本—— 没有 .nvmrc，package.json 里也没有 engines。也就是说 CI 的版本是「碰巧」是 20， 哪天镜像换默认版本，它自己就漂了。

让版本只有一个来源

三处都指向同一个文件：

# .nvmrc
22.11.0

// package.json
"engines": { "node": ">=22.11.0" }

# CI
- uses: actions/setup-node@v4
  with:
    node-version-file: .nvmrc

.nvmrc 给本地（nvm use 直接生效），engines 给「装错版本时至少有个警告」， CI 的 node-version-file 读的是同一份——以后升版本只改 .nvmrc 一处。

顺手把包管理器也钉住

同一个漂移问题在 npm 上也成立：本地 10.x、CI 9.x，锁文件格式不同，npm ci 会直接失败。 package.json 里加一行 "packageManager": "npm@10.9.0" 就够，CI 不需要额外步骤。

还要补一道门

版本对齐之后，两边仍可能因为「本地装过、CI 没装」而结果不同。CI 上补一步 npm ci --ignore-scripts 之后跑一次 npm ls --all 的校验，装不全就直接失败， 比等测试跑一半报模块找不到要省时间。

结果

三处改完之后重跑，CI 上的失败消失；把 .nvmrc 改成 20 再跑一次，CI 如实复现了本地的失败—— 说明两边现在读的确实是同一份版本声明。

抽成什么样

三段重复的其实是同一件事：从 Authorization 头取出 token、解析、把结果放进 context。抽成一个 authenticate，三种调用方式各包一层薄的：

type Result struct {
	Subject string
	Scopes  []string
}

func authenticate(next func(http.ResponseWriter, *http.Request, Result)) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		res, err := parseBearer(r.Header.Get("Authorization"))
		if err != nil {
			writeAuthError(w, err) // 401 / 403 的判定只在这一处
			return
		}
		next(w, r, res)
	})
}

抽的时候要注意

1. 错误语义别丢：现在三段里有两段把「没带 token」和「token 过期」都回 401，第三段回的是 403。合并前先确认哪种是对的，别顺手把差异抹平——客户端可能正靠这个区分「去登录」和「去申请权限」；
2. 日志里的调用方标识：有一段会往日志里写 sub，另两段不写。合并后统一写，但字段名要与已有的对齐，否则看板的查询要跟着改；
3. 顺序：中间件在链上的位置不一样，其中一段挂在路由级、两段挂在全局。抽出来后位置保持原样，不要「顺便统一」。

测试先跑一遍再动手，改完再跑一遍，两次数目一致才算没漏。

根因

refresh token 是一次性轮换的：换新的同时旧的作废。并发场景下两个请求带着同一个 refresh token 过来，第一个换走了，第二个撞上「已作废」，于是回 401——客户端看到的就是偶发掉线。

客户端先收敛成单飞

同一时刻只允许一个刷新在飞，其余请求等它的结果：

let inflight: Promise<Tokens> | null = null;

export function refresh(): Promise<Tokens> {
  inflight ??= doRefresh().finally(() => {
    inflight = null;
  });
  return inflight;
}

关键在 finally 里清空：失败也要清，否则一次网络抖动会让后面所有请求都拿到同一个失败的 Promise。

服务端还得容忍重放

单飞只挡住了同一个进程内的并发。网络重试、多标签页、移动端切前后台都会造成同一个旧 token 被用两次，所以服务端要留一个宽限窗口：旧 token 在换掉后的一小段时间内再用一次，返回同一个新 token，而不是直接判失效。窗口取 30 秒就够——比任何一次重试的间隔都长，又短到不至于让被窃取的 token 一直能用。

两边都改完，压测里并发刷新的 401 从每千次 7 次降到 0。