架构设计 on 牛哥聊技术

PancakeSwap V3 深度解析（下）：合约篇

Sun, 03 May 2026 10:00:00 +0800

前言

本文是「PancakeSwap V3 深度解析」系列的下篇——合约篇。

上篇讲了 V3 的协议设计：集中流动性、tick 离散化、NFT 仓位、TWAP 预言机，以及 PancakeSwap 在协议层独有的 3 处改动（0.25% 费率档、LMPool 协议级挖矿 hook、FarmBooster + veCAKE）。

本文把这些协议设计落到合约源码：V3 fork 共有的合约设计是怎么实现的、PancakeSwap 在合约层加了哪些东西、那些"咒语级名词" sqrtPriceX96 / tickBitmap / feeGrowthInside 翻译成人话到底是什么意思。重点说清楚两件事——* NonfungiblePositionManager 与 Pool 的聚合仓位关系*，以及回调收款模式为什么这么设计。

系列阅读：上篇·协议篇 → 下篇·合约篇（本文）

一、项目结构

PancakeSwap V3 的合约代码分布在几个独立的 project 里，各司其职：

1
2
3
4
5


projects/
├── v3-core/ # 核心池合约（AMM 引擎）
├── v3-periphery/ # 外围合约（NFT 仓位管理、流动性管理）
├── router/ # 路由合约（交易聚合、多跳）
└── masterchef-v3/ # 流动性挖矿合约（PancakeSwap 独有）

为什么要拆这么散？一句话：v3-core 是绝对不能改、不能升级的部分。它是所有外围合约信任的基石，一旦升级就要重新部署所有池、迁移所有流动性。所以 Uniswap / PancakeSwap 都把 core 锁得死死的（连接口都很 minimal），然后把"用户友好"的逻辑——比如 NFT 化、滑点检查、多跳路由、池初始化——全部下沉到可替换的 periphery 层。

v3-periphery 容易被遗漏，但它承载了普通用户最常打交道的 NonfungiblePositionManager——所有 LP 仓位都是通过它铸造成 NFT 的。Core 的 Pool 本身只认"聚合仓位"，根本不关心 NFT。

masterchef-v3 是 PancakeSwap 独有的——Uniswap V3 没有对应模块，激励是另一个独立 repo 的 UniswapV3Staker 外挂合约。

二、合约层次架构

完整的调用层次如下：

flowchart TD
 User([用户 / 前端])
 Router["SmartRouter
交易路由"]
 MC["MasterChefV3
挖矿质押"]
 Quoter["QuoterV2
报价"]
 PM["NonfungiblePositionManager
NFT 仓位管理"]
 Pool["PancakeV3Pool
核心 AMM 池"]
 Factory["PancakeV3Factory
池注册表"]
 Deployer["PancakeV3PoolDeployer
CREATE2 部署"]

 User --> Router
 User --> MC
 User --> Quoter
 MC -. NFT.safeTransfer .-> PM
 Router --> Pool
 PM --> Pool
 Quoter --> Pool
 Pool --> Factory
 Factory --> Deployer

 classDef user fill:#fef3c7,stroke:#d97706,color:#000
 classDef entry fill:#dbeafe,stroke:#2563eb,color:#000
 classDef pos fill:#fce7f3,stroke:#db2777,color:#000
 classDef pool fill:#ede9fe,stroke:#7c3aed,color:#000
 classDef factory fill:#dcfce7,stroke:#16a34a,color:#000

 class User user
 class Router,MC,Quoter entry
 class PM pos
 class Pool pool
 class Factory,Deployer factory

PancakeV3Pool 内部维护的核心状态：

1
2
3
4
5
6
7


Slot0: sqrtPriceX96, tick, observationIndex, feeProtocol, unlocked
ticks: mapping(int24 => Tick.Info)
tickBitmap: mapping(int16 => uint256) // O(1) 找下一个已初始化 tick
positions: mapping(bytes32 => Position.Info) // 聚合仓位
observations: Oracle[65535] // 历史价格，用于 TWAP
liquidity: uint128 // 全局活跃流动性
feeGrowthGlobal0/1: uint256 (Q128.128) // 单调累加的手续费增长

每一层的职责一句话总结：

层级	合约	职责
入口	SmartRouter / MasterChefV3 / QuoterV2	用户操作的入口，聚合多池路由、质押、报价
仓位	NonfungiblePositionManager	把 LP 仓位 NFT 化，管理用户的份额与待领手续费
核心	PancakeV3Pool	单个交易对的 AMM 引擎，处理 swap / mint / burn / collect
工厂	PancakeV3Factory	创建池、维护 fee tier 与 tickSpacing 映射
部署	PancakeV3PoolDeployer	通过 CREATE2 确定性部署 Pool

三、与 Uniswap V3 合约的实质差异

PancakeSwap V3 的合约树和 Uniswap V3 在 90% 的代码上一致——同一套 AMM 数学、同一套回调收款模式、同一套 CREATE2 池部署。* 但有几处合约层的实质差异值得专门拎出来*——读源码时碰到 Uniswap 没有的代码，基本都集中在这几处。

3.1 PancakeV3Pool 内部多了 LMPool hook

这是合约层最大的差异。PancakeV3Pool.swap() 内部多了两处挖矿钩子调用——

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


function swap(...) external override returns (...) {
 // ...
 IPancakeV3LmPool _lmPool = lmPool; // 池绑定的挖矿合约
 if (address(_lmPool) != address(0)) {
 _lmPool.accumulateReward(uint32(block.timestamp)); // ← 累加奖励
 }

 // ... while loop 跨 tick
 if (state.liquidity > 0) {
 // ...
 if (step.initialized) {
 if (address(_lmPool) != address(0)) {
 _lmPool.crossLmTick(step.tickNext, zeroForOne); // ← 跨 tick 时通知
 }
 // ... ticks.cross()
 }
 }
}

Uniswap V3 的 UniswapV3Pool.swap() 完全不知道挖矿——这两行 hook 是 PancakeSwap 在 core 里加的协议级改动。代价是每次 swap 多 5-10k gas，收益是挖矿状态与 Pool 状态在同一笔交易里同步更新，没有第三方监听延迟。

3.2 多了 PancakeV3LmPool 合约

每个 PancakeV3Pool 部署时，会通过 LmPoolDeployer 同时部署一个 PancakeV3LmPool 实例，与 Pool 1:1 绑定。这个合约维护：

每个 tick 的 rewardGrowthOutside
全局 rewardGrowthGlobal
当前 reward rate（每秒释放多少 CAKE）

Uniswap V3 没有对应合约——它的 UniswapV3Staker 是独立合约，每个 NFT 在 stake 时单独记账，Pool 完全不感知。

3.3 MasterChefV3 vs UniswapV3Staker

	UniswapV3Staker	MasterChefV3
与 Pool 的关系	完全外挂，Pool 不感知	通过 LmPool 与 Pool 在 swap 路径上同步
奖励来源	任何 ERC20（项目方注入）	主要是 CAKE，由协议挖矿释放
Boost	没有	FarmBooster 1x~2x（基于 veCAKE）
Stake 形式	把 NFT 锁进合约	NFT.safeTransferFrom 给 MasterChef
奖励计算	stake 时记快照，unstake 时算差值	每次 swap 同步累加，collect 时算差值

差异的根因是上篇讲过的"协议级 hook vs 外挂"——MasterChefV3 能在 swap 路径上同步累加，因为 Pool 主动调用 LmPool；UniswapV3Staker 只能等用户主动操作时才更新。

3.4 FarmBooster + veCAKE 集成

FarmBooster 合约根据用户的 veCAKE 余额计算 1x~2x 的乘数。MasterChefV3.updateLiquidityOperation() 在更新 LP 流动性时会主动调用 FarmBooster，把 raw liquidity 放大成 boostLiquidity。Uniswap V3 没有任何对应合约。

3.5 费率档位常量

1
2
3
4
5


// PancakeV3Factory 构造函数
feeAmountTickSpacing[100] = 1; // 0.01% (与 Uniswap 相同)
feeAmountTickSpacing[500] = 10; // 0.05% (与 Uniswap 相同)
feeAmountTickSpacing[2500] = 50; // 0.25% (Uniswap 是 3000 / 60)
feeAmountTickSpacing[10000] = 200; // 1.00% (与 Uniswap 相同)

注意 Uniswap V3 后来通过治理也加过 0.01% 档，但 0.30% 一直在，PancakeSwap 没有 0.30% 而是 0.25%——这导致两套池的 fee tier 完全不能相互替代。

3.6 命名 / 前缀差异（仅 rename）

合约名都从 UniswapV3* 改为 PancakeV3*，callback 函数名相应改为 pancakeV3MintCallback / pancakeV3SwapCallback / pancakeV3FlashCallback。这只是 rename，不影响 ABI 兼容性，对理解逻辑没有任何障碍。

理解了这 6 处差异，剩下 90% 的内容与 Uniswap V3 高度相似——后面的章节大部分思路和细节也适用于读 Uniswap V3 的源码。

四、核心合约详解

4.1 Factory + PoolDeployer：为什么要拆成两个？

V3 把"池的部署"从 Factory 中剥离出来，单独放在 PoolDeployer。这是个工程决定，根源在于以太坊的合约 bytecode 上限（EIP-170，约 24KB）。

PancakeV3Pool 的 bytecode 已经接近上限了。如果 Factory 里直接 new PancakeV3Pool(...)，Pool 的完整 bytecode 会被嵌进 Factory 的 bytecode，Factory 自己直接爆体积。拆分后：

Factory 只负责：校验参数、记录 getPool 映射、调用 PoolDeployer。
PoolDeployer 只负责：把构造参数写入 storage → CREATE2 部署 Pool → Pool 构造函数从 PoolDeployer 读取参数 → 清空 storage。

为什么 Pool 不直接从构造参数取？因为 CREATE2 要求 bytecode 完全一致（地址 = keccak256(0xff, deployer, salt, keccak256(bytecode))），如果把 token 地址塞到构造参数里，每个 Pool 的 bytecode 就不一样了。所以 Pool 的构造函数是无参的，从外部 storage 读——这是一个非常有意思的"曲线救国"。

最终效果：salt = keccak256(token0, token1, fee)，Pool 的地址在部署前就可以离线算出。这也是为什么 Periphery 合约里到处看到 PoolAddress.computeAddress(...)——根本不需要查 Factory，直接算就完事了，省一次 SLOAD。

4.2 PancakeV3Pool：核心数据结构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 全局热点状态，塞进一个 storage slot
struct Slot0 {
 uint160 sqrtPriceX96; // 当前价格（平方根表示, Q64.96）
 int24 tick; // 当前 tick
 uint16 observationIndex;
 uint16 observationCardinality;
 uint16 observationCardinalityNext;
 uint8 feeProtocol;
 bool unlocked; // 重入锁
}

mapping(int24 => Tick.Info) public ticks; // 每个 tick 的元信息
mapping(int16 => uint256) public tickBitmap; // O(1) 查找下一个已初始化 tick
mapping(bytes32 => Position.Info) public positions; // key = keccak(owner, tickLower, tickUpper)

Slot0 把所有"每次 swap 都要读"的字段塞进了一个 256-bit 槽（160 + 24 + 16 + 16 + 16 + 8 + 8 = 248，刚好压得进去）。这样 swap 路径上读这些字段的成本从 N 次 SLOAD 降到 1 次。这种"压槽"是 V3 抠 gas 的代表手法，几乎每个核心结构体都做了这件事。

Tick 是什么？为什么用 sqrt(price)？

V3 把价格离散化成 tick，关系是：

$$ \text{price}(i) = 1.0001^i, \quad i \in \mathbb{Z} $$

也就是说每个 tick 之间正好差 1 个基点（0.01%）。tick = 0 对应价格 1，tick = 6932 大约对应 2，tick = -6932 大约对应 0.5。tick 是整数，这一点很重要——所有 tick 边界比较都是整数比较，极度便宜。

那为什么 slot0 里存的不是 price，而是 sqrtPriceX96？因为 V3 的核心公式涉及 √price 的差分：

$$ \Delta \sqrt{P} = \frac{\Delta y}{L}, \qquad \Delta \frac{1}{\sqrt{P}} = \frac{\Delta x}{L} $$

其中 L 是流动性。如果存 price，每次 swap 都要做开方，gas 直接劝退。直接存 √price，所有运算都是加减乘除。

X96 是 Q64.96 定点数：整数部分 64 bit，小数部分 96 bit，合起来 160 bit，正好塞进 uint160。换算到普通价格：

1

realPrice = (sqrtPriceX96 / 2**96) ** 2

第一次读到 sqrtPriceX96 这个名字的时候我也懵过几分钟，把它翻译成"用定点数表示的 √price"立刻就清楚了。

4.3 NonfungiblePositionManager：NFT 化的仓位管理

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


struct Position {
 uint96 nonce; // permit nonce
 address operator; // 授权操作者
 uint80 poolId; // 池 ID（指向 _poolIdToPoolKey）
 int24 tickLower;
 int24 tickUpper;
 uint128 liquidity; // 该 NFT 的流动性份额
 uint256 feeGrowthInside0LastX128; // 上次快照
 uint256 feeGrowthInside1LastX128;
 uint128 tokensOwed0; // 待领取的手续费
 uint128 tokensOwed1;
}

这里有个关键设计：在 Pool 的 positions 映射里，所有通过同一个 PositionManager 来的用户仓位，会按 (PositionManager 地址, tickLower, tickUpper) 聚合成一个仓位；每个 NFT 只在 PositionManager 自己的 _positions[tokenId] 里记录份额和上次的 feeGrowthInside 快照。

这是 V3 最值得单独拎出来讲的一处设计，下面第六节会展开。

五、核心流程时序

5.1 创建池

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


用户 → Factory.createPool(tokenA, tokenB, fee)
 │
 ├─ 校验: tokenA != tokenB、fee tier 已启用、池未存在
 │
 ├─ Factory → PoolDeployer.deploy(factory, token0, token1, fee, tickSpacing)
 │ ├─ 写 Parameters 到 storage
 │ ├─ CREATE2 部署 PancakeV3Pool(salt = keccak256(token0, token1, fee))
 │ ├─ Pool 构造函数从 PoolDeployer.parameters() 读取参数
 │ └─ 清除 Parameters
 │
 ├─ 写双向映射 getPool[token0][token1][fee] = pool
 └─ emit PoolCreated

值得注意的是，createPool 之后池还没有被初始化——slot0.sqrtPriceX96 = 0，任何 swap / mint 都会 revert。需要 Periphery 的 PoolInitializer.createAndInitializePoolIfNecessary() 来设定初始价格，或者直接调用 Pool.initialize(sqrtPriceX96) 。第一个调用方决定了池的开盘价，也因此开池后的第一笔 mint 通常需要项目方先动手，防止套利者按操控价开池。

5.2 添加流动性（Mint）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


用户 → NonfungiblePositionManager.mint(params)
 │
 ├─ addLiquidity() [LiquidityManagement.sol]
 │ ├─ 计算 pool 地址（CREATE2）
 │ ├─ 读 pool.slot0() 获取当前价格
 │ ├─ LiquidityAmounts.getLiquidityForAmounts() 算出 liquidity
 │ │
 │ └─ Pool.mint(address(this), tickLower, tickUpper, liquidity, callbackData)
 │ ├─ _modifyPosition() → _updatePosition()
 │ │ └─ 更新 Pool.positions 中的【聚合仓位】
 │ │
 │ └─ callback: pancakeV3MintCallback(amount0, amount1, data)
 │ ├─ verifyCallback() 校验回调来源
 │ └─ pay(token, payer=用户, recipient=Pool, amount)
 │
 ├─ _mint(recipient, tokenId++) // 铸造 ERC721
 ├─ 缓存 poolId(_poolIds + _poolIdToPoolKey)
 ├─ 读 Pool 聚合仓位的 feeGrowthInside 作为快照
 └─ 把 Position 存到 _positions[tokenId]
 └─ emit IncreaseLiquidity(tokenId, liquidity, amount0, amount1)

这里要重点说一下 V3 标志性的回调收款模式。Pool 是先记账（更新 liquidity、positions）、再回调让调用方付款、最后用 balanceBefore / balanceAfter 校验确实收到钱。

为什么不先收钱再记账？因为先收钱意味着用户必须在调用前把代币 approve 给 Pool，然后 Pool 在 mint 里 transferFrom 用户。这套流程在 V2 也用过，但有两个问题：

需要两步交易（approve + mint），用户体验差。
Pool 必须信任用户授权额度的合理性，而 Pool 是个永生合约，授权一旦给出基本不会撤回——这是钓鱼攻击最爱的入口。

回调模式把支付逻辑外包给调用者（通常是 Periphery 合约），Pool 只在事后校验"我余额是不是真的多了 X"。这样：

Pool 自己不需要任何 approve，授权链断在 Periphery 处。
调用方可以是任何合约，包括 flash mint（借出来再还回去），原生支持闪电贷语义。
多步操作可以原子地组合在一次 callback 里（比如 swap-and-mint）。

代价是：Pool 必须能识别"调用者是不是合法的"——这通过 verifyCallback() 完成，本质是再算一次 PoolAddress.computeAddress(...) 比对 msg.sender。

5.3 交换（Swap）—— 最核心的路径

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


用户 → SmartRouter.exactInputSingle(params)
 │
 └─ V3SwapRouter.exactInputInternal()
 ├─ 解析 path: tokenIn / tokenOut / fee
 ├─ 确定方向 zeroForOne = tokenIn < tokenOut
 │
 └─ Pool.swap(recipient, zeroForOne, amountSpecified, sqrtPriceLimitX96, data)
 ├─ lock() 重入锁
 ├─ LmPool.accumulateReward() // 若开启挖矿
 │
 ├─ while 循环（逐 tick 跨越）:
 │ ├─ tickBitmap.nextInitializedTickWithinOneWord() 找下一个 tick
 │ ├─ SwapMath.computeSwapStep() 算本步 amountIn/Out/fee
 │ ├─ 扣协议费，累加 feeGrowthGlobal
 │ ├─ 如果到达 tick 边界:
 │ │ ├─ LmPool.crossLmTick() // 若开启挖矿
 │ │ └─ ticks.cross() 跨越 tick、更新流动性
 │ └─ 直到 amountSpecified 用尽或撞到价格上限
 │
 ├─ 更新 slot0(sqrtPrice、tick、observation)
 ├─ 更新全局 liquidity
 │
 ├─ 先把 output token 转给 recipient
 ├─ callback: pancakeV3SwapCallback(amount0, amount1, data)
 │ └─ Router 把 input token 打进 Pool
 ├─ 校验 Pool 余额确实增加
 └─ emit Swap

一个具体例子：跨 tick 是怎么发生的？

假设当前 ETH/USDC 池价格 P = 2000，tick = 76012，池里只有两个流动性区间：

LP-A: 在 [1900, 2100] 区间，liquidity = 1000
LP-B: 在 [1950, 2050] 区间，liquidity = 500

当价格在 2000 时，两个区间都覆盖当前价格，池的活跃流动性 liquidity = 1500。

现在有人 swap 卖 USDC 买 ETH，价格上涨。Pool 的 while 循环大致这么走：

第 1 步：从 P=2000 涨到下一个 tick 边界 tick(2050)。这一步用 liquidity=1500 计算需要多少 USDC 输入、能换多少 ETH 输出。
跨越 2050：LP-B 的上界，流动性减少 500。Pool 调用 ticks.cross()，更新 liquidity = 1000。
第 2 步：从 P=2050 继续涨，这次只用 liquidity=1000 算。如果用户的输入还没花完，继续往上走。
跨越 2100：LP-A 的上界，流动性再减 1000，变成 0。这意味着池子在更高价格上没有任何做市了——再想买 ETH 只能换更高价的池或别的路径。
如果用户的 amountSpecified 还没用完，但 liquidity = 0，swap 就在这里停住，剩余的 input 退还。

这就是为什么 V3 的 LP 必须主动管理价格区间：价格穿出区间，你的流动性就"下班"了——不再赚手续费，而且仓位会变成单边币（穿出上界变成纯 token0，穿出下界变成纯 token1）。

跨 tick 的 gas 代价

每跨越一个已初始化的 tick，大约要多花 20k gas（一次 SSTORE 反转 tickBitmap + 读写 ticks.Info）。所以密集做市的池子在大额 swap 时会比稀疏池贵很多。这也是为什么你会在区块浏览器上看到一些 V3 swap 的 gas 飙到 30 万以上——那都是跨了十几个 tick 的大单。

5.4 流动性挖矿（MasterChef V3）

关于"为什么挖矿是协议级 hook 而非外挂"，已在上篇协议篇与本篇第三节展开，这里只看合约实现细节。

质押（Deposit）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


用户 → NFT.safeTransferFrom(user, MasterChefV3, tokenId)
 │
 └─ MasterChefV3.onERC721Received()
 ├─ 读 NFT 的 (token0, token1, fee, liquidity, ticks)
 ├─ 找对应的 pid
 ├─ LMPool.accumulateReward()
 ├─ updateLiquidityOperation()
 │ ├─ 更新 position.liquidity
 │ ├─ 通过 FarmBooster 算 boostLiquidity（1x ~ 2x）
 │ └─ LMPool.updatePosition(tickLower, tickUpper, liquidityDelta)
 └─ emit Deposit

收割（Harvest）：

1
2
3
4
5
6


用户 → MasterChefV3.harvest(tokenId, to)
 │
 ├─ LMPool.accumulateReward()
 ├─ LMPool.getRewardGrowthInside(tickLower, tickUpper)
 ├─ reward = (rewardGrowthDelta * boostLiquidity) / Q128
 └─ CAKE.safeTransfer(to, reward)

注意 reward 的算法和手续费是同构的：都是"区间内增长 × 流动性份额"，只不过一个累加 fee，一个累加 CAKE。理解了 feeGrowthInside，rewardGrowthInside 就是免费的副产品。

六、聚合仓位设计：V3 的精髓

这是整个 V3 体系里最值得单独拎出来讲的一处。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


Pool.positions[key] ——【聚合仓位，全局共享】
┌──────────────────────────────────────────┐
│ key = keccak256(PositionManager 地址, │
│ tickLower, tickUpper) │
│ │
│ liquidity = 所有 NFT 流动性之和 │
│ feeGrowthInside = 累计手续费增长 │
│ tokensOwed0/1 = (聚合层不实际使用) │
└──────────────────────────────────────────┘

PositionManager._positions[tokenId] ——【个体仓位，NFT 私有】
┌──────────────────────────────────────────┐
│ liquidity = 该 NFT 的份额 │
│ feeGrowthInsideLast = 上次快照值 │
│ tokensOwed0/1 = 待领取手续费 │
│ poolId → (token0, token1, fee) │
└──────────────────────────────────────────┘

一个具体例子

假设 Alice 和 Bob 都通过 PositionManager 在同一个区间 [1900, 2100] 做市：

Alice mint：liquidity = 100
Bob mint：liquidity = 200

Pool 端只看到一个位于该区间的仓位，liquidity = 300。Pool 不知道 Alice 是谁，也不知道 Bob 是谁。

这时发生了一笔 swap，该区间累计产生 9 USDC 手续费。Pool 把这笔费用按"区间内的总流动性"折算成 feeGrowthInside 的增量，假设增量是 +ΔF。

Alice 来 collect 时：

她的 feeGrowthInsideLast 是 mint 时的快照。
当前 feeGrowthInside 比她的快照多了 ΔF。
她应得 = ΔF × 100 / 2^128 = 3 USDC（对应她占 1/3 的流动性份额）。

Bob 同理拿到 6 USDC。Pool 端没有任何"分账"逻辑——所有的份额结算全部下放到 PositionManager，在用户来交互时一次性算出来。

为什么这么设计？

省 gas。Pool 只关心"每个区间总共有多少流动性"，不需要知道有几个 LP。无论 1 个还是 1000 个 LP 同区间做市，Pool 端的存储成本完全一样。
结算延迟到读取时。每个 NFT 的待领手续费 = (当前 feeGrowthInside − 上次快照) × liquidity。用户没操作时，合约**完全不需要 **为他更新状态——所有"利息"都是用户下次交互时一次性结算的。这是把"懒计算"用到极致。
份额化与可组合性。NFT 化让仓位可以被转让、抵押、再封装（MasterChefV3 直接接收 NFT 来做加权挖矿就是个例子）。如果 Pool 端按用户分账，这一切都做不了。

理解了这个设计，你会发现 V3 的 Mint 流程里"先读 Pool 聚合仓位的 feeGrowthInside 作为快照，再写到 NFT 自己的 _positions“那一步——它就是在记下"我这次进场时世界长什么样”，方便下次出场时算差值。

七、关键设计模式

模式	应用	解决的问题
工厂 + CREATE2	PoolDeployer 用 salt 确定性部署 Pool	池地址离线可算，绕开 bytecode 24KB 上限
回调收款	Mint / Swap / Flash 都用 callback	Pool 不需要 approve，授权链断在 Periphery，天然支持闪电贷
重入锁	`slot0.unlocked`，塞在热点槽里	Pool 级互斥，零额外 SLOAD 成本
Tick Bitmap	`mapping(int16 => uint256)`	一个 word 覆盖 256 个 tick，O(1) 找下一个已初始化 tick
Oracle 累加器	`observations` 环形数组	记录 `tick * time` 累加和，任意时间窗口的 TWAP 是减法
Boost	FarmBooster 动态调节 1x~2x	给 veCAKE 长期锁仓者激励
Fee Growth 全局累加	`feeGrowthGlobalX128` 单调递增	按"区间内累加差值 × 流动性"分账，延迟结算
聚合仓位	PositionManager 在 Pool 端只占一个 position	LP 数量与 Pool 存储成本解耦

关于 Oracle 累加器多说一句

observations 数组里存的不是某一时刻的价格，而是 tick 的时间积分 tickCumulative = ∫ tick dt。计算 [t1, t2] 区间的 TWAP，只需要：

1
2


twapTick = (cumulative(t2) - cumulative(t1)) / (t2 - t1)
twapPrice = 1.0001 ** twapTick

两次查询、一次减法、一次除法，就拿到任意窗口的均价。这种"前缀和差分"的 trick 在 DeFi 里被反复使用，记住它你能看懂大半个生态的预言机实现。

八、踩坑提醒 / 常见误区

整理几个我自己读这套合约时被绊到、或者看到别人栽的坑：

tickLower / tickUpper 必须是 tickSpacing 的倍数。每个 fee tier 有自己的 tickSpacing（0.01% → 1, 0.05% → 10, 0.25% → 50, 1% → 200）。直接传任意 tick 会 revert。
liquidity 不是"我存了多少钱"，而是一个抽象量，大致是 √(x * y) 的某种归一化。同样的 liquidity 在窄区间消耗的代币远少于宽区间。前端报的"$value" 是它根据当前价反算出来的。
burn() 不会把代币转给你——它只是把流动性从 Pool 里"出账"到你的 tokensOwed。要拿到币必须再调一次 collect()。这是 V3 一个反直觉的两步设计。
手续费是单独累加的，不是自动复投。LP 想要复投，要主动 collect 之后再 increaseLiquidity。不少前端会把这个流程包成一键，但合约层面是两步。
swap 的 amountSpecified 是有符号数：正数表示精确输入（exactIn），负数表示精确输出（exactOut）。
Periphery 上的 deadline / slippage 是 Periphery 加的，Core 没有。直接对着 Pool 调 swap 是没有滑点保护的——这就是为什么大家都通过 Router 走。
NFT 转给 MasterChefV3 之后，你不能直接 collect 手续费了。手续费的归属逻辑被 MasterChefV3 接管，要通过它的接口去取。
Pool 的 feeProtocol 是协议费，不是 LP 手续费。它从 swap 收的 fee 里再切一刀（默认为 0，治理可改），只有打开后才会进 protocolFees 累加器。
PancakeSwap 的 0.25% 档与 Uniswap 的 0.30% 档不互通。如果你做跨 DEX 聚合，这是要单独写映射的。

九、数据流总结

1
2
3
4


Token 流 : 用户 → Router → Pool ↔ NonfungiblePositionManager
奖励流 : Receiver → MasterChefV3 → 用户(CAKE)
信息流 : Pool.tick / tickBitmap / position → LMPool → MasterChefV3
报价流 : QuoterV2 → Pool.swap(用 revert 捕获结果，不实际成交)

Quoter 的报价机制值得单独提一下：它直接调 Pool.swap()，但在自己的 callback 里 revert 抛出计算结果——既不修改状态也不需要任何代币授权， 白嫖了 Pool 的全部计算逻辑做模拟。这是在 EVM 上做"只读模拟"的标准技巧之一，放在 V3 这种逻辑复杂的池子上特别划算（否则前端要自己重新实现 SwapMath，极易出 bug）。

十、附录：数学速查

名词	公式 / 说明
tick → price	`price = 1.0001 ^ tick`
price → tick	`tick = log(price) / log(1.0001)`
sqrtPriceX96	`sqrtPriceX96 = sqrt(price) * 2^96`（Q64.96 定点数）
真实价格	`price = (sqrtPriceX96 / 2^96) ^ 2`
区间内代币关系	`Δ√P = Δy / L`，`Δ(1/√P) = Δx / L`
feeGrowthInside	`feeGrowthGlobal − feeGrowthBelow(tickLower) − feeGrowthAbove(tickUpper)`
LP 应得手续费	`(feeGrowthInside_now − feeGrowthInside_snapshot) × liquidity / 2^128`
TWAP	`(tickCumulative(t2) − tickCumulative(t1)) / (t2 − t1)`

Q64.96：整数部分 64 bit、小数部分 96 bit，合计 160 bit，正好放进 uint160。feeGrowth / rewardGrowth 用的是 Q128.128（ uint256）——因为它要承载更长时间的累加，精度需求更高。

结语

PancakeSwap V3 的合约体系并不算"难懂"，但很致密——几乎每一处设计都是为了在"集中流动性"这个核心命题下，把 gas 抠到极致、把状态压到最小。如果只看一遍 Pool，你会觉得它复杂；但当你理解了：

Factory / Deployer 拆分是为了绕开 bytecode 限制；
Slot0 的压槽是为了把 swap 路径上的 SLOAD 压到 1 次；
聚合仓位是为了让 LP 数量与 Pool 存储成本解耦；
回调模式是为了让 Pool 不必信任任何调用方却仍能正确收款；
feeGrowth / tickCumulative 都是同一种"前缀和差分"思想；
LMPool / MasterChefV3 / FarmBooster 是 PancakeSwap 在 Uniswap V3 之上的协议级延伸；

你会发现整个架构其实非常一致——所有看似奇怪的拆分，都是在回答同一个问题：**怎么在以太坊的 gas 预算下，把一个连续函数的做市逻辑跑起来。 **

下一篇打算单独写 tick / tickBitmap / liquidityNet 是怎么把"集中流动性"在链上落地的，以及 SwapMath 那段循环每一步到底在算什么——把数学和 Solidity 一一对上。

系列阅读：上篇·协议篇 → 下篇·合约篇（本文）

如果这篇有讲不清楚的地方，欢迎在评论区或邮件指出。

PancakeSwap V3 深度解析（上）：协议篇

Sun, 19 Apr 2026 16:00:00 +0800

写在前面

PancakeSwap V3 和 Uniswap V3 的关系经常被简化成一句"前者是后者的 fork"——这话一半对一半不对。

协议设计上，PancakeSwap V3 确实继承自 Uniswap V3：同样的集中流动性、同样的 tick 离散化、同样的 NFT 仓位、同样的 TWAP 预言机。这些东西先讲清楚，再来谈细节。

但 PancakeSwap V3 不是简单复制粘贴——它在协议层做了 3 处实质性扩展：

费率档位不同：0.01% / 0.05% / 0.25% / 1.00%（Uniswap 是 0.30% 不是 0.25%），tickSpacing 也跟着不同
挖矿是协议级 hook，不是外挂：Pool 合约内部预留 LMPool 调用，与 swap 在同一笔交易里更新奖励
FarmBooster + veCAKE：基于 veCAKE 锁仓量给挖矿 1x ~ 2x 加权，Uniswap 完全没有

顺带一提的背景：Uniswap V3 上线时是 BSL（2 年内禁止商用 fork），PancakeSwap V3 是 BSL 到期后才合规 fork 并改造——这是商务/合规层面的事，不算协议扩展。

本文是「PancakeSwap V3 深度解析」系列的上篇——协议篇，讲清楚 V3 是什么、为什么这么设计、LP 怎么用，以 PancakeSwap V3 为讲解载体，会随时标出哪些是 V3 共性、哪些是 PancakeSwap 独有。下篇会拆 PancakeSwap V3 的合约源码。

系列阅读：上篇·协议篇（本文） → 下篇·合约篇

一、V2 的局限：资金被"摊薄"

不论是 Uniswap V2 还是 PancakeSwap V2，资金池模型都是同一套：

1
2


价格 = y / x
不变量：x × y = k

LP 的资金均匀分布在 0 到 ∞ 的价格区间上——

flowchart LR
 LP[LP 提供流动性] --> Pool["资金均匀分布
(0 → ∞)"]
 Pool --> Inefficient[绝大部分资金
在『不可能成交』的价格区间]

实际交易主要发生在某个价格附近——绝大部分 LP 资金永远不会被用到。

例子：USDC/CAKE 池——市场价 $2.5，LP 投入的资金里，$0.0001 / $1000000 这种价格区间的资金完全闲置。

二、V3 的核心：集中流动性

V3 让 LP 可以只把资金投入到自选的价格区间：

flowchart LR
 LP[LP] --> Range["选择价格区间
e.g., $2.4-$2.6"]
 Range --> Concentrated[资金集中在该区间]
 Concentrated --> HighEfficiency[资金效率提升 10-1000 倍]

如果你 100% 确信 USDC/CAKE 价格在 $2.4-$2.6 之间——只在这个区间提供流动性，资金效率比 V2 高几十倍。

但有代价——价格走出区间时，你的资金"失效"：

价格 < 你的下界 → 全部变成 CAKE（不再赚手续费）
价格 > 你的上界 → 全部变成 USDC（不再赚手续费）

这就是 LP 必须主动管理仓位的原因——V3 不再是『躺赚』，是『主动做市』。

三、Tick 与费率档位

V3 把连续的价格空间离散化成 tick——每个 tick 对应一个价格：

1

price(i) = 1.0001 ^ i

每两个相邻 tick 之间价格变化 0.01%。LP 选区间时不能选任意价格——只能选 tick 边界。

不同费用等级有不同的 tickSpacing——这里就是 PancakeSwap 与 Uniswap 协议层的第一处实质差异：

Pool 费率	PancakeSwap V3 tickSpacing	Uniswap V3 对比
0.01%	1	1（相同）
0.05%	10	10（相同）
0.25%	50	0.30% / 60
1.00%	200	200（相同）

PancakeSwap 把中间档从 0.30% 调到 0.25%，并且配套 tickSpacing=50。这小幅让利给 trader，叠加 PancakeSwap 在 BNB Chain 上的低 gas 成本，主流 BNB token 池子大多集中在这一档。做跨 DEX 聚合 / 路径搜索时要注意——PancakeSwap 0.25% 档和 Uniswap 0.30% 档 不是同一档，聚合器配置或自实现路径时不能简单地把它们当作等价 fee tier。（顺带一提：两个协议的池子本来就是独立合约、流动性不互通，价格只通过套利者在链下慢慢趋同。）

低费率适合稳定币对——价格变化小、tickSpacing 也小；高费率适合波动大的资产——粗 tick 节省 Gas。

四、NFT 仓位：每个仓位是独立 NFT

V2 的 LP token 是 ERC-20——所有 LP 同质化。 V3 的 LP 仓位是 ERC-721 NFT——每个仓位独一无二：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


struct Position {
 uint96 nonce;
 address operator;
 uint80 poolId;
 int24 tickLower;
 int24 tickUpper;
 uint128 liquidity;
 uint256 feeGrowthInside0LastX128;
 uint256 feeGrowthInside1LastX128;
 uint128 tokensOwed0;
 uint128 tokensOwed1;
}

每个仓位 NFT 包含：

流动性大小
价格区间（tickLower, tickUpper）
累计未提取的手续费

NFT 化的好处：

每个仓位独立管理——可以转让、抵押、组合
二级市场可能——交易"已经做好的 LP 仓位"
DeFi 可组合——其他协议可以包装 V3 仓位（如 Range Protocol、DefiEdge，见第十节）

PancakeSwap 在这一层和 Uniswap 是 1:1 一致的——NonfungiblePositionManager 实现几乎完全继承，只是 callback 方法名带了 pancakeV3* 前缀。

五、费用结算

V3 的费用结算极其精巧——每个 tick 跨越时累积 fee growth：

1
2


全局：feeGrowthGlobal0_X128, feeGrowthGlobal1_X128
每个 tick：feeGrowthOutside0_X128, feeGrowthOutside1_X128

LP 提取手续费时计算：

1

feeGrowthInside = feeGrowthGlobal - feeGrowthBelow - feeGrowthAbove

这套设计让每个 LP 仓位的累计费用都能精确计算——不管交易在哪个 tick 发生。

PancakeSwap V3 在 fee growth 旁边额外维护了一份 reward growth（用于 CAKE 挖矿），公式同构，见第九节。

六、跨多个 tick 的 swap

用户发起 swap 时，价格可能跨越多个 tick：

flowchart LR
 Trade["用户卖出 100 CAKE"] --> Step1["在 tick 1000 区间内
swap 50 CAKE"]
 Step1 --> Cross1["跨越 tick 边界"]
 Cross1 --> Step2["在 tick 1001 区间内
swap 30 CAKE"]
 Step2 --> Cross2["跨越 tick 边界"]
 Cross2 --> Step3["在 tick 1002 区间内
swap 20 CAKE"]

每跨越一个 tick——激活/失活该 tick 上的 LP 仓位。这是 V3 实现"集中流动性"的工程细节。

每跨越一个已初始化的 tick 大约多花 20k gas——密集做市的池子在大额 swap 时会比稀疏池贵很多。

七、TWAP：时间加权平均价

V3 提供更强大的 价格预言机——记录每个 block 的 tick 累加，能算任意时间窗口的 TWAP：

1
2
3
4
5
6
7
8


// 查询过去 30 分钟的 TWAP
uint32[] memory secondsAgos = new uint32[](2);
secondsAgos[0] = 1800;
secondsAgos[1] = 0;

(int56[] memory tickCumulatives, ) = pool.observe(secondsAgos);
int24 avgTick = (tickCumulatives[1] - tickCumulatives[0]) / 1800;
uint256 price = TickMath.getSqrtRatioAtTick(avgTick);

抗操纵性强——攻击者要操纵 TWAP 必须持续多个 block 推价格，成本极高。

但短窗口仍可被操纵——闪电贷攻击常见。生产用 30 分钟 TWAP 比较安全。

PancakeSwap V3 的 TWAP 实现与 Uniswap V3 完全一致。

八、做市策略

V3 的 LP 不再是"投入忘掉"——需要主动策略：

1. 被动 LP

把仓位放在很宽的范围——类似 V2 但收益略高。简单但效率低。

2. 紧仓位 + 频繁调整

把仓位放在当前价格附近 ±1%——资金效率最高，但要频繁调整避免价格走出。需要机器人。

3. JIT（Just-In-Time）流动性

监控 mempool——发现大单交易要进来时临时投入流动性赚一笔手续费，立刻撤回。

4. 范围订单（Range Orders）

1
2


当前价 $2.5，想以 $3 卖 CAKE？
→ 在 $3 单边提供 CAKE（一旦价格到 $3，自动转换成 USDC）

V3 的"单边流动性"等同于"限价订单"。

5. PancakeSwap 特有：质押 NFT 进 MasterChefV3 挖 CAKE

把 NFT 转给 MasterChefV3 后，除了原本的 swap 手续费，还能赚 CAKE 奖励。这是其他 V3 fork 没有的玩法，详见下一节。

九、PancakeSwap 协议层特有：原生挖矿与 FarmBooster

这是 PancakeSwap V3 与 Uniswap V3 在协议层最显著的差异。

原生挖矿 vs 外挂 Staker

Uniswap V3 的官方激励是个外挂合约 UniswapV3Staker：

Pool 本身不知道有挖矿
用户把 NFT 存进 Staker
Staker 监听 NFT 上的事件来分配奖励
优点：Pool 保持纯净；缺点：激励发放和 swap 不在同一笔交易里更新，有套利空间

PancakeSwap V3 把挖矿做成了协议级 hook：

1
2
3
4


Pool.swap()
 ├─ 正常的 swap 逻辑
 ├─ LMPool.accumulateReward() ← Pool 主动调用
 └─ 跨 tick 时 LMPool.crossLmTick() ← Pool 主动调用

LMPool 是 Pool 部署时绑定的伴生合约，和 Pool 是 1:1 关系。Pool 在 swap 和跨 tick 时主动通知 LMPool 累加奖励——这意味着挖矿状态 永远和 Pool 状态同步，没有第三方监听延迟。

代价是：这笔 hook 调用本身会增加 swap 的 gas（大约 5-10k 额外开销）。

FarmBooster：veCAKE 的 1x ~ 2x 加权

FarmBooster 是 PancakeSwap 的另一处独有设计——用户持有 veCAKE 越多，挖矿权重越高：

1
2


boostMultiplier = 1.0 + min(veCAKE / threshold, 1.0) // 1x ~ 2x
boostedLiquidity = liquidity × boostMultiplier

也就是说，同样的 LP 仓位，长期锁了 CAKE 的人能拿到最多 2 倍奖励。这是个软锁仓激励——拉长 CAKE 的平均锁仓周期，稳定治理。

奖励结算复用 V3 的同构机制

挖矿奖励的算法和手续费完全同构：

概念	swap 手续费	CAKE 挖矿
全局累加器	`feeGrowthGlobal`	`rewardGrowthGlobal`
Tick 累加器	`feeGrowthOutside`	`rewardGrowthOutside`
区间内累加	`feeGrowthInside`	`rewardGrowthInside`
LP 应得	`(ΔfeeGrowthInside) × liquidity / 2^128`	`(ΔrewardGrowthInside) × boostedLiquidity / 2^128`

理解了 V3 的费用结算，你就免费理解了 PancakeSwap 的挖矿结算——只是把"swap 来的 fee"换成了"按时间释放的 CAKE"，再叠了 boost 系数。

十、V3 仓位管理生态

由于 V3 仓位需要主动管理，出现了一批"V3 流动性管理"协议——它们包装 V3 NFT 给用户提供"V2-like 简单体验"，牺牲一部分收益换简单。

Ethereum / Uniswap V3 生态（主战场）：

Arrakis Finance：自动管理 V3 仓位的金库
Gamma Strategies：算法策略管理仓位
Charm Finance

BNB Chain / PancakeSwap V3 生态：

Range Protocol：跨链 V3 流动性管理，支持 PancakeSwap V3
DefiEdge：多链 V3 仓位策略
Bril Finance：专注 PancakeSwap V3 的自动复投金库

整体来说 BNB 链的 V3 管理生态比以太坊小一截——但 PancakeSwap V3 自带的 MasterChefV3 + FarmBooster 已经覆盖了"被动持有 + 自动收益"的大部分场景，第三方管理的需求没那么强。

十一、PancakeSwap V3 的真实数字

TVL：历史高峰在 $15-20 亿区间（DeFiLlama 多链合计，BNB Chain 主导，2024 年起以太坊和 Arbitrum 部署增长明显）
日交易量：稳定数亿美元，经常超过 Uniswap V3 在 BNB Chain 上的所有相关池子
支持链：BNB Chain、Ethereum、Arbitrum、Polygon zkEVM、zkSync Era、Linea、Base、opBNB 等
MasterChefV3 总质押 NFT 数：数万，锁定 LP 中相当大的比例
CAKE 挖矿：每 block 释放，通过 FarmBooster 倾斜给 veCAKE 持有者

PancakeSwap V3 是 BNB Chain DEX 流动性的事实标准——大多数 BNB 链 token 的"主流动性"都在这里。

十二、对开发者的启发

读 PancakeSwap V3 源码（pancakeswap/pancake-v3-contracts）能学到的：

大数运算：Q128.128 / Q64.96 定点数实现
位操作优化：tick 状态用 bitmap 管理
NFT 化金融头寸：仓位 ERC-721 化的工程范式
链上费用结算：精确到任意 tick 区间
预言机设计：TWAP 抗操纵
协议级挖矿 hook：LMPool 与 Pool 1:1 绑定的设计——这是 PancakeSwap 的独特贡献，值得对比 Uniswap V3 + Staker 的外挂思路学习

V3 的代码量不多但密度极高——是 DeFi 工程师的必读源码。

小结

把 PancakeSwap V3 的价值压一句：

V3 用『集中流动性 + tick 离散化 + NFT 仓位』把 LP 从『被动的资金池』升级为『主动的做市策略』，PancakeSwap 在此基础上加了协议级挖矿 + veCAKE Boost，把 CAKE 经济和流动性深度捆绑。

理解 V3 协议的几个关键（与 Uniswap V3 共性）：

LP 选区间，资金集中——效率几十倍
价格离散化为 tick——便于工程实现
每个仓位是 ERC-721 NFT——可组合、可交易
TWAP 提供抗操纵的预言机
LP 不再是『躺赚』——需要主动管理

PancakeSwap 在协议层的独有设计：

0.25% 费率档（对 Uniswap 0.30%）
协议级挖矿 hook（LMPool）——不是外挂
FarmBooster + veCAKE——锁仓激励 1x~2x

下一篇我们把这些协议设计落到合约层——拆 PancakeV3Factory、PancakeV3Pool、NonfungiblePositionManager、MasterChefV3 的源码，看看每一行代码是怎么把上面这些抽象概念实现出来的。

继续阅读：PancakeSwap V3 深度解析（下）：合约篇

逻辑主键还是业务主键？数据库主键设计的取舍与最佳实践

Tue, 25 Nov 2025 15:30:00 +0800

写在前面

数据库主键看似简单——但选错了能让一个表"永远改不动":

业务编码当主键 → 业务规则一变全表 rebuild
UUID 当主键 → 索引性能差、空间膨胀
自增 ID → 跨库迁移血泪
雪花 ID → 时钟回拨能让你怀疑人生

新人常困惑——到底该选哪个？本文讲清五种主流方案（自增 BIGINT、UUID v4、UUID v7、雪花 ID、业务键作主键）的优劣、取舍、典型场景。

一、概念先分清：逻辑主键 vs 业务主键

逻辑主键

和业务无关的"内部标识"——纯技术存在。

自增 BIGINT
UUID
雪花 ID

特点：业务永远改不到它，因为它没有业务含义。

业务主键

业务上有意义的字段——天然唯一。

用户表用 username
订单表用 order_no
商品表用 sku_code

特点：业务可能要求改格式、改前缀、改长度。

这两个概念是冲突的——主键应该用哪一种？答案不是非黑即白。

二、五种主流方案

方案 1：自增 BIGINT 逻辑主键（推荐默认）

1
2
3
4
5
6


CREATE TABLE user (
 id BIGINT PRIMARY KEY AUTO_INCREMENT,
 username VARCHAR(64) UNIQUE,
 name VARCHAR(64),
 -- ...
);

优点：

写入性能极好——InnoDB 按主键聚簇，递增 ID 永远 append
索引体积小——8 字节
JOIN 高效——整数比较快
业务编码可以单独建索引、独立演化

缺点：

跨库迁移痛——两库的自增 ID 必然冲突
单库瓶颈——发号依赖单一数据库
暴露业务规模——id=1234567 攻击者能猜测总量
不适合分布式场景

适用：单库或简单分库（按业务键分库）的小到中型项目。80% 的业务表用这个。

方案 2：UUID

1
2
3
4


CREATE TABLE user (
 id BINARY(16) PRIMARY KEY,
 -- ...
);

优点：

全球唯一——零中心化
跨库无冲突
不暴露业务规模

缺点：

写入性能差——UUID 无序，每次插入都可能引发页分裂
空间大——16 字节，char(36) 文本形式更是 36 字节
索引差——B+ Tree 上散列严重
JOIN 慢——字符串比较开销大

用 UUID 一定要 BINARY(16) 不能 CHAR(36)——16 字节 vs 36 字符，索引和 JOIN 性能差距巨大。

适用：离线生成 ID 的场景（移动端先生成、再上传）、对中心化发号有强烈反感的场景。多数 Web 业务不推荐。

方案 3：UUID v7（时间有序 UUID）

UUID v7（2024 RFC 9562 标准）解决了 UUID 的写入性能问题——前 48 位是毫秒时间戳：

1

018D2DA1-7000-7XXX-XXXX-XXXXXXXXXXXX

优点：

时间递增——索引友好
全球唯一——分布式无冲突

缺点：

仍然 16 字节，比 BIGINT 大
会暴露生成时间（精确到毫秒）——和雪花 ID 一样，敏感场景需评估
工具/框架支持还在普及中

这是 2024 后比 v4 更值得用的 UUID 形式——多数语言库已经支持。

方案 4：雪花 ID（Snowflake）

Twitter 设计的分布式 ID 算法——64 位结构：

1
2


| 1 bit | 41 bits | 10 bits | 12 bits |
| 符号 | 时间戳（毫秒） | 工作机器 ID（5 bit dc + 5 bit machine） | 序列号 |

10 bit 机器位 Twitter 原版就拆成 5 bit datacenter + 5 bit worker，最多支持 32 个数据中心 × 32 台机器 = 1024 节点。

优点：

64 位 BIGINT——和自增 ID 一样紧凑
时间递增——索引友好
分布式无中心
高吞吐（每节点每毫秒 4096 个）

缺点：

时钟回拨问题——服务器时钟跳回会重复 ID
机器 ID 分配——上千节点时管理麻烦
还是暴露业务速率（每毫秒能生成多少）

适用：分布式系统的标准选择。美团 Leaf、百度 UidGenerator 都是改进版。

方案 5：业务键作主键（不推荐）

1
2
3
4


CREATE TABLE user (
 username VARCHAR(64) PRIMARY KEY,
 -- ...
);

优点：

表自描述
少一个字段

缺点：

业务规则一变就完蛋（比如 username 长度要扩展）
VARCHAR 主键聚簇索引大、慢
关联表的外键也要 VARCHAR——空间和性能双爆炸
业务编码可能为空（早期数据没填）→ 主键不能为空 → 全表数据迁移

多数 OLTP 场景都不推荐这么做——除非表很小且业务键真正稳定不变。

三、决策树

flowchart TD
 Start([单库还是分布式?])
 Start -->|单库| Small{规模小?}
 Start -->|分布式| Snow[雪花 ID 或 UUID v7]
 Small -->|是| Auto[自增 BIGINT]
 Small -->|否，将来要分库| Snow

90% 的场景按这个流程决定：

小型系统、单库 → 自增 BIGINT
可能分库或一开始就分布式 → 雪花 ID
离线生成 / 强分布式无中心 → UUID v7

四、生产级雪花 ID 的实现要点

朴素雪花算法在生产里有不少坑——成熟方案要解决：

1. 时钟回拨

绝对禁止时钟跳回——可能导致 ID 重复。处理方案：

启动时检查时钟，跳了就拒绝启动
运行时检测，跳了就等回到原点再发号（短暂阻塞）
改进版用 bit 当回拨标志位

2. 机器 ID 分配

朴素方案要在配置文件里写死 worker_id——上千节点时是地狱。生产方案：

ZooKeeper / etcd 自动分配
进程启动时主动注册
退出时主动释放

3. 数据中心 ID

如上所述 Twitter 原版就把 10 bit 拆成 5+5；如果你的部署只有一个 DC，可以把 datacenter 位让渡给 worker 位，扩展到 1024 台单 DC 节点。

4. 序列号回滚

朴素方案每毫秒序列号从 0 开始——容易在毫秒边界 burst 时浪费。改进：

上一毫秒的序列号末位作为下一毫秒的起点（散列写入）

5. 实战推荐

直接用：

美团 Leaf：github.com/Meituan-Dianping/Leaf
百度 UidGenerator：github.com/baidu/uid-generator

不要自己手写——这些库覆盖了所有边界。

五、对外暴露的"业务编码"

无论用什么主键，对外暴露通常都不直接用主键——而是用业务编码：

1
2
3
4
5


CREATE TABLE order (
 id BIGINT PRIMARY KEY AUTO_INCREMENT,
 order_no VARCHAR(32) UNIQUE NOT NULL, -- 对外
 -- ...
);

order_no 用规则生成：

1

ORD202511250001234 (前缀 + 日期 + 序号)

为什么"对外用 order_no、对内用 id"？

对外不暴露业务规模——order_no 看不出实际订单数
支持改格式——order_no 改前缀不影响内部关联
可读——客服发"订单号 ORD…"，比"id=12345"友好

这是国内大多数生产系统的标准姿势。

六、几个常见反模式

反模式 1：业务编码当主键 + 加 `_old` 字段做迁移

业务规则改了 → 加 username_old 字段保留老的 → 后续查询要 WHERE username = ? OR username_old = ? ——永远的技术债。

反模式 2：UUID 用 char(36)

1

id CHAR(36) PRIMARY KEY -- ❌

应该用 BINARY(16)——空间和性能差距巨大。

反模式 3：自增 ID 暴露给前端

前端 URL 里 ?orderId=12345 ——攻击者枚举可以拿到所有订单。用业务编码或者对 ID 做混淆（如 hashids 库）。

反模式 4：复合主键

1

PRIMARY KEY (user_id, order_id)

复合主键麻烦多——外键关联痛苦、ORM 支持不好、加新维度时改表复杂。永远用单字段主键 + 唯一索引表达组合唯一。

反模式 5：自增 + UUID 双主键

“我两个都要！"——同时维护两个 ID 维护成本高、容易产生不一致。单一真理来源（single source of truth）——只有一个主键。

七、性能数据对比

10 亿行表，单条 INSERT 的耗时（实测大致比例）：

	写入耗时	索引大小	JOIN 速度
BIGINT 自增	1×	1×	1×
雪花 ID	1×	1×	1×
BINARY(16) UUID v7	1.2×	2×	1.2×
BINARY(16) UUID v4	5×（页分裂严重）	2×	1.2×
CHAR(36) UUID	8×	4×	5×
VARCHAR 业务键	6×	3×	4×

差距在大数据量场景被无限放大。

八、实战 Checklist

设计新表时按这个清单：

主键用 BIGINT 自增 / 雪花 ID
业务编码加唯一索引 但不当主键
VARCHAR 主键不允许（除非超小表）
UUID 用 BINARY(16) + v7 不要 v4 / char(36)
关联表外键用主键 ID，不要用业务编码
对外 API 用业务编码，不暴露主键
重要表的业务编码生成有规则（前缀 + 日期 + 序号 / hashids）
分布式场景用雪花 ID，不要自己撸

九、关于"零号 ID”

很多人争论 ID 应该从 0 还是 1 开始——约定俗成是从 1 开始：

id = 0 在 Java / Go 里是基本类型默认值——容易混淆"未设" vs “设为 0”
业务上"用户 0"听起来怪
一些 ORM 把 id = 0 视为"新对象未保存"

让 ID 从 1 开始是最少踩坑的约定。

小结

把全文压一句：

主键应该是业务无关的、稳定的、紧凑的——业务编码独立另存，对外用编码、对内用主键。这是数据库表能长期演化的基础。

工程纪律：

新表默认 BIGINT 自增——简单可靠
分布式上雪花 ID
UUID 用 v7 + BINARY(16)
绝不用 VARCHAR 业务键作主键
业务编码加唯一索引 + 对外暴露
主键不暴露给前端

把这些做对，你的表能跑 10 年——而不是一年后就要做"主键迁移"这种最痛的事。

Protobuf 协议原理解析：为什么它能比 JSON 小一半还快几倍

Thu, 06 Nov 2025 15:30:00 +0800

写在前面

写过 gRPC 或 Dubbo 的人都见过 .proto 文件：

1
2
3
4
5


message User {
 int64 id = 1;
 string name = 2;
 repeated string tags = 3;
}

编译生成代码、序列化、传输——业务里只用到几行 API，但底层 Protobuf 的二进制格式做了非常多巧妙的设计。

理解 Protobuf 的内部原理对工程有几个直接价值：

能解释为什么 Protobuf 比 JSON 小一半——不只是"去掉了字段名"那么简单
能避免字段编号变更导致的兼容性灾难
能在性能敏感场景做出精准选型

本文从 wire format 到 Varint 到字段标签，把 Protobuf 的核心机制讲清楚。

一、为什么不是 JSON

JSON 的问题：

字段名占大量空间——{"username": "alice", "age": 30} 字段名比值还长
数字编码冗余——123456789 当字符串编码要 9 字节
解析慢——要 tokenize、要 parse、要 build object
无 schema——不知道字段类型，要靠运行时推断

Protobuf 的解法：

字段名替换为编号——username 变成 1，age 变成 2
数字用 Varint——小数字用更少字节
二进制 stream 解析——按 schema 直接读
schema 是契约——sender / receiver 都依赖同一个 .proto

二、Wire Format：字段的二进制表示

每个字段在 wire 上都是 (tag, value) 的形式。tag 由两部分组成：

1

tag = (field_number << 3) | wire_type

field_number：在 .proto 里定义的字段编号（如 name = 2 中的 2）
wire_type：3 位，表示 value 的编码方式

Wire Types

Type	名称	用途
0	Varint	int32 / int64 / uint32 / uint64 / bool / enum
1	64-bit	fixed64 / sfixed64 / double
2	Length-delim	string / bytes / message / packed
5	32-bit	fixed32 / sfixed32 / float

类型 3、4 是 group 类型（已弃用）。

例子

message Person { string name = 1; int32 age = 2; }，对应数据 {name: "abc", age: 30}：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


field 1, wire_type 2 (string):
 tag = (1<<3) | 2 = 0x0A
 length = 3 (varint)
 value = "abc" → 61 62 63

field 2, wire_type 0 (varint):
 tag = (2<<3) | 0 = 0x10
 value = 30 (varint) → 0x1E

整个二进制：
 0A 03 61 62 63 10 1E

只有 7 字节——而 JSON 的 {"name":"abc","age":30} 是 22 字节。

三、Varint：变长整数编码

Varint 是 Protobuf 的核心创新——小数字用更少字节，大数字才用多字节。

编码规则

每个字节的最高位（MSB）作为"还有更多字节"的标志：

MSB = 1 → 后面还有
MSB = 0 → 这是最后一个字节
其余 7 位是 payload

编码示例

数字 1：

1
2


binary: 00000001
Varint: 00000001 (1 byte)

数字 300：

1
2
3
4
5


binary: 100101100 (9 bits)
groups of 7: 0000010 0101100
按小端: 0101100 0000010
加 MSB: 1010 1100 0000 0010
hex: AC 02

数字越小占的字节越少：

数字范围	Varint 字节数
0 - 127	1
128 - 16383	2
16384 - 2M	3
2M - 268M	4
268M+	5

业务里 ID 多数小于 2 亿——Varint 比定长 8 字节 int64 节省 50% 以上。

Varint 的代价

负数特别大：-1 在补码下是 0xFFFFFFFF...FFFF（10 字节），所有负数都用 10 字节
解决：sint32 / sint64 用 ZigZag 编码——正负数交替排列，让 -1, 1, -2, 2 都很小

1
2
3
4
5


sint32 编码: (n << 1) ^ (n >> 31)
-1 → 1
1 → 2
-2 → 3
2 → 4

有负数的字段一定要用 sint32 / sint64——否则空间浪费惊人。

四、Length-delimited：字符串和子消息

string、bytes、嵌套 message、packed repeated 都用 length-delimited：

1

[tag][length][bytes...]

length 也是 Varint——所以 1 字节就能表示 0-127 字节的内容。

嵌套 message

1
2
3
4
5


message Address { string city = 1; }
message Person {
 string name = 1;
 Address addr = 2;
}

嵌套消息不是"展开"——而是当作一段嵌入的二进制流：

1
2
3
4


field 2 (addr):
 tag = (2<<3) | 2 = 0x12
 length = N (varint)
 value = [Address 的完整序列化字节]

这意味着——Protobuf 的解析器是递归的，但内存效率极高。

五、字段编号：兼容性的命脉

字段编号是 Protobuf 兼容性的核心约定——一旦定了，永不能改：

1
2
3
4
5


message User {
 int64 id = 1;
 string name = 2;
 string email = 3; // 之后加的
}

兼容规则

新增字段 → 老 client 解析时跳过未知字段（不报错）
删除字段 → 字段编号永不复用，加 reserved 防止
改类型 → 大多数情况会破坏兼容（除少数兼容对，如 int32 ↔ int64）
改字段名 → 不影响 wire（wire 只用编号）但破坏代码层面 API

reserved 的用法

1
2
3
4
5
6
7
8


message User {
 reserved 4, 5;
 reserved "old_field";

 int64 id = 1;
 string name = 2;
 // ...
}

防止后人不小心复用了已删除的字段编号——会编译错误。

字段编号的成本

1-15 编号占 1 字节 tag
16-2047 占 2 字节
2048+ 占 3 字节

高频字段尽量用 1-15 编号——能省一字节。

六、Repeated 和 packed 编码

1

repeated int32 ids = 4;

默认编码（proto2）：每个元素单独发一遍 tag + value：

1

tag value tag value tag value ...

[packed = true]（proto3 默认）：合并成单个 length-delimited 块：

1

tag length value value value ...

packed 显著节省空间——尤其当数组元素都是小数字时。proto3 默认 packed，proto2 要显式声明。

七、Proto2 vs Proto3

Proto2

字段标记 required / optional / repeated
默认值显式声明
区分"未设置"和"等于默认值"

Proto3

删掉 required 和 optional（后又部分恢复）
字段总是 optional
默认值不发送
packed 默认开启

现状

新项目用 proto3——更简洁
2020 年后 proto3 又支持 optional——能区分"没设" vs “等于默认值”
老项目用 proto2 也没问题，但社区主要在 proto3

八、性能对比

	JSON	Protobuf	Avro	MessagePack
体积（典型业务对象）	1×	0.4-0.5×	0.4×	0.6×
序列化速度	1×	5-10×	5×	3×
反序列化速度	1×	5-10×	5×	3×
跨语言	✓	✓	✓	✓
人类可读	✓	✗	✗	✗
Schema 强约束	✗	✓	✓	✗

Protobuf 的核心优势：体积 + 速度 + schema 一致性。核心劣势：不可读 + 必须先有 schema。

九、什么场景用 Protobuf

✅ 适合：

gRPC 服务调用——Protobuf 是 gRPC 默认序列化
微服务间通信——schema 强约束，避免字段约定问题
移动端 / IoT ——节省带宽
批量数据处理（Hadoop / Kafka）——高吞吐
存储优化——某些 KV 存储用 Protobuf 序列化 value

❌ 不适合：

对外 REST API——前端期望 JSON
小项目 / 调试期——要 .proto 文件 + 编译器，启动成本高
schema 频繁变化——每次都要发版
需要人类可读——Protobuf 没法直接看

十、几个工程踩坑

1. 字段编号永不复用

1
2
3
4


message User {
 // 删除了 string old_field = 4;
 string new_field = 4; // ❌ 不能复用编号 4！
}

老 client 拿到新数据时会把 new_field 的内容当成 old_field 解析——数据被错乱。永远 reserved。

2. enum 默认值

1
2
3
4


enum Status {
 PENDING = 0; // 必须有 0 值（默认）
 ACTIVE = 1;
}

proto3 强制 enum 必须有 0 值——这个值代表"未设置"。业务设计 enum 时考虑这个。

3. 大消息分包

某些 RPC 框架对单个 message 大小有限制（如 gRPC 默认 4MB）——大数据要 stream 而非单包：

1
2
3


service FileService {
 rpc Upload(stream FileChunk) returns (UploadResp);
}

4. 字符串编码

Protobuf string 必须是合法 UTF-8——塞二进制数据用 bytes 类型，否则解析会失败。

5. Optional 的 has 方法

proto3 的 optional 字段才能区分"没设"和"等于默认值"——普通字段无法区分：

1
2
3
4


message User {
 int32 age = 1; // 普通：age = 0 和"没设"无法区分
 optional int32 score = 2; // optional：能区分
}

业务模型设计时考虑——重要的"是否存在"语义字段加 optional。

十一、Protobuf 与 gRPC 的关系

很多人误以为"Protobuf = gRPC"——其实它们独立：

Protobuf：序列化协议
gRPC：基于 HTTP/2 的 RPC 框架，默认用 Protobuf

Protobuf 也能用在：

不走 gRPC 的 RPC（如 Dubbo3 的 Triple 协议）
Kafka 消息序列化
自己写的二进制协议
文件存储

小结

把全文压一句：

Protobuf 不只是『二进制 JSON』——它是 schema-driven 序列化的范式：用编号代替字段名、用 Varint 节省空间、用 wire type 保证可解析、用兼容规则保证演进。

工程要点：

字段编号永不复用
小数字用 Varint，负数用 sint
重要字段用 1-15 编号
enum 必须有 0 值
packed repeated 默认开
大数据用 stream RPC

理解 Protobuf 的内部原理——下次再排查"为什么我的 protobuf 数据 client 解不出来"时，你能瞬间想到是字段编号被改了还是类型不兼容。

Compound 协议解析：DeFi 借贷的奠基者

Tue, 28 Oct 2025 16:00:00 +0800

写在前面

DeFi 圈子里有几个绕不过去的奠基者协议：

MakerDAO：把法币概念引入链上（DAI 稳定币）
Uniswap：把 AMM（自动做市商）做到极致
Compound：把链上借贷做成可组合金融基础设施

Compound 由 Robert Leshner 和 Geoffrey Hayes 在 2018 年推出。它创造了几个让整个 DeFi 沿用至今的范式：

cToken 模型：把"存入资产"变成可流通的代币
算法利率：根据资金池利用率自动调整借贷利率
流动性挖矿（COMP 代币）：开启 DeFi 真正的"治理代币热"
预言机喂价：所有借贷依赖外部价格

如果你想理解 Aave、Venus、JustLend 等借贷协议——先吃透 Compound。本文讲清楚它的核心机制和工程价值。

一、Compound 在做什么

简单说——Compound 是一个去中心化的"借贷池"。任何人可以：

存入资产（USDC、ETH、DAI 等支持的资产）→ 赚利息
抵押资产借出（用你的存款做抵押借出别的资产）

flowchart LR
 Lender[出借人] -->|存入 USDC| Pool[(资金池)]
 Borrower[借款人] -->|抵押 ETH| Pool
 Pool -->|借出 USDC| Borrower
 Pool -->|利息| Lender

没有撮合——所有用户对的是"池子"，不是另一个用户。

二、cToken：存款的代币化

存进 Compound 的 USDC 不是普通存款——你换回了 cUSDC：

1

存入 100 USDC → 收到约 5000 cUSDC（按当前 exchange rate ≈ 1 USDC : 50 cUSDC）

cUSDC 是一种 ERC-20 代币：

数量代表你对池子的份额
池子产生利息时，cToken 总数不变，但 exchange rate 持续上涨——也就是 1 cUSDC 能兑换的 USDC 越来越多
取回时把 cUSDC 烧掉换回 USDC（按当前 exchange rate）

flowchart LR
 User -->|deposit 100 USDC| Compound
 Compound -->|mint ~5000 cUSDC| User
 Note1[初期 exchange rate ≈ 0.02 USDC/cUSDC]
 Note2[一年后 exchange rate ≈ 0.0213 USDC/cUSDC
同样 5000 cUSDC 现在能换回 ~106 USDC]

也就是说，同样数量的 cUSDC 能换回的 USDC 持续增加——这就是利息累积的体现。

cToken 的革命性：它是可组合的金融乐高——你可以把 cUSDC：

存进 Yearn 等收益聚合器
在 DEX 上交易
作为其他 DeFi 协议的抵押品

不像传统银行存款只是个数字——cToken 是真实的可流通资产。

三、算法利率模型

利率不是固定的——根据资金池的"利用率"动态调整：

1

利用率 U = 借出量 / 总存款

利率公式（简化）：

1
2


borrowRate = baseRate + U × multiplier // 利用率低时
borrowRate = baseRate + U × multiplier + (U - kink) × jumpMultiplier // U 超过 kink 后陡升

直觉：

池子很多人借 → 借款利率上升 → 抑制借款 / 鼓励存款 → 平衡池子
池子没什么借款 → 利率低 → 减少存款利息 / 鼓励借款 → 平衡池子

flowchart LR
 LowU[利用率低] --> LowRate[低利率] --> AttractBorrow[吸引借款]
 HighU[利用率高] --> HighRate[高利率] --> AttractDeposit[吸引存款]

Compound 的"利率曲线" 让市场自动平衡——不需要中心化机构定价。

四、抵押与清算

借款必须超额抵押——比如借 70 USDC 要抵押价值 100 ETH。

Collateral Factor

每种资产有一个 Collateral Factor（抵押因子）——比如 ETH 是 75%、稳定币 90%。

你抵押 1000 USD 的 ETH（CF=75%）→ 最多能借 750 USD 等值的资产

健康因子

1

Health Factor = (抵押品价值 × CF) / 借款价值

HF > 1：安全
HF < 1：可被清算

清算机制

如果 ETH 价格暴跌让 HF 跌破 1——任何人都可以触发清算：

清算者替借款人还一部分债（最多 50%）
清算者以折扣价拿走借款人的抵押品（折扣通常 5-8%）

flowchart LR
 BorrowerHF[借款人 HF=0.95] --> Anyone[任何人]
 Anyone -->|repay 50% debt| Pool
 Pool -->|reward 105% collateral| Anyone

清算者赚 5% 差价——这是激励清算者监控市场的机制。链上有专门的"清算机器人"24x7 盯着所有借款人的 HF。

五、COMP 治理代币与流动性挖矿

2020 年 6 月 Compound 上线了 COMP 代币——治理用：

总量 1000 万
每天向用户分发——根据"借入 + 存款总额"按比例
持有 COMP 可以参与协议治理（提案、投票）

这一改动点燃了整个 DeFi 行业的"流动性挖矿"狂潮：

用户存款不仅能赚利息，还能赚 COMP——COMP 价格高时，挖矿收益甚至超过本金利息。

短短几周——Compound 总锁仓量从几亿美元飙到几十亿。Aave、SushiSwap、Curve 等无数协议跟进发币——DeFi 进入"DeFi Summer"。

治理实践

COMP 持有者可以：

提议加新借贷市场
调整 Collateral Factor
调整利率曲线参数
升级合约

Compound 是真正实现了"协议自治"的样板——团队渐渐退出，决策由代币持有者做。

六、预言机：Compound 的命门

所有借贷决策都依赖资产价格——清算判断、抵押率计算都要价格输入。

Compound 早期使用 Open Price Feed——以 Coinbase Pro（后改名 Coinbase Exchange）作为主要签名报价方，配合 Uniswap V2 TWAP 做防御。设计预期是接入更多 reporter，但实际上 Coinbase 长期是唯一稳定上报的数据源。

但预言机被攻击的案例不少——经典案例是 2020 年 11 月 26 日 DAI 在 Coinbase Pro 价格异常飙升，导致 Compound 上约 8900 万美元的资产被异常清算。这是 DeFi 借贷协议永远的 risk——单源预言机一旦被推、被异常波动，整个清算系统就被绑架。

V3 之后 Compound 全面切到 Chainlink 等专业预言机——多源 + 时间加权 + 偏离阈值 多重保护，把这类风险显著降低。

七、cToken vs aToken vs dToken

不同借贷协议的"存款代币"模型有差异：

	Compound (cToken)	Aave V2 (aToken)	Aave V3 (aToken)
余额变化	数量不变，价格上涨	数量上涨，价格 = 1	数量上涨
用户体验	看着不增长（要折算）	看到余额秒级增长	同 V2
复合性	✓	✓	✓

aToken 用户体验上更好——钱包里看到余额持续增长，比 cToken 直观。Compound 后来推出的 V3 借鉴了 aToken 模型。

八、Compound V2 vs V3

Compound V2（2019）：当时被称为"DeFi 借贷的标准"。

Compound V3（2022）——重大改变：

每个市场只有一种借出资产（如 USDC 池只能借 USDC）——避免协议级流动性碎片化
抵押品和借出资产分离——你抵押 ETH 借 USDC，但 ETH 不会被借出去
简化治理——更专注、更易管理

V3 的设计哲学是 “做对一件事”——让借贷更安全、更可预测，但灵活性比 V2 低一些。

九、Compound 的影响和遗产

直接受影响的协议

Aave - 借贷模型几乎完全师承 Compound
Venus（BNB 链） - Compound V2 的 fork
JustLend（Tron） - Compound V2 的 fork
Benqi（Avalanche） - Compound V2 的 fork

Compound 的开源代码被复制粘贴到了几乎所有 EVM 链——是 DeFi 借贷的"参考实现"。

留下的范式

池化借贷（vs P2P 撮合）
算法利率
代币化存款（cToken）
链上清算激励
流动性挖矿 / 治理代币

这些都是 Compound 第一个推广——后续协议都在它的基础上演化。

十、Compound 的局限与反思

1. 高 Gas 费

每次存款 / 借款 / 清算都是链上交易——以太坊高峰期单次操作 $50+。这是为什么 Compound 在 L2 / 侧链才能让小用户负担得起。

2. 系统性风险

借贷协议的风险叠加：

预言机被攻击 → 清算异常
某个抵押品资产暴跌 → 大量清算 → 价格进一步下跌（连环反应）
智能合约 bug → 资金被盗

Compound 历史上有过几次小事故——DAI 利率公式 bug 短暂导致部分清算异常，但整体记录良好。

3. 治理参与度低

虽然有 COMP 投票——多数提案投票率不高。“代币持有者治理"在理论上美好，实践中常常是『大户投票决定一切』。

4. 复杂性对小用户不友好

抵押率、利率曲线、清算阈值——普通人很难弄懂。这是 DeFi 至今没能真正"出圈"的痛点之一。

十一、对开发者的启发

读 Compound 源码（github.com/compound-finance/compound-protocol）能学到很多：

CToken.sol：cToken 实现，学习"代币化金融头寸"的范式
Comptroller.sol：协议核心控制器，学习如何用单合约管理多市场
InterestRateModel.sol：利率模型——算法定价的实战案例
PriceOracleProxy.sol：预言机抽象层
Governance.sol：治理合约

这些不是"教学代码”——是真实管理着数十亿美元资金的代码，工程质量在 DeFi 中属于标杆水平。

小结

把 Compound 的价值压一句：

Compound 不只是一个借贷协议——它是 DeFi 的『结构性创新者』，定义了池化借贷、算法利率、流动性挖矿等几乎所有 DeFi 沿用至今的范式。

理解它的几个关键：

cToken = 代币化的存款 + 利息
算法利率根据利用率动态调整
清算激励让市场自动维持安全
COMP 让协议进入"代币治理"时代
V3 进一步简化和专注

如果你做 DeFi 借贷类项目——绝不要 fork Compound 就上线。要理解每一行代码、每一个参数的含义。Compound 的代码值得反复研读—— 是 DeFi 工程师值得花时间啃的源码之一。

数据字典表与菜单的国际化方案

Fri, 19 Sep 2025 15:30:00 +0800

写在前面

国内系统做国际化常常掉进一个误区——以为前端搞个 i18n 文件就完事了。但当业务真要支持多语言（出海、跨境电商、海外 SaaS）时，你会发现：

错误消息从后端来——前端 i18n 没用
数据字典（订单状态、产品类型）从 DB 来——前端写死翻译会脱节
菜单和按钮文本从配置中心来——前端 i18n 不能覆盖
营销内容/邮件模板/短信模板都要多语言

真正的国际化是『后端数据 + 前端展示』的协同。本文围绕数据字典和菜单这两个最难的场景，给出生产级方案。

一、为什么数据字典国际化最难

普通业务表的国际化简单——加个 _en 字段就完事。但数据字典特殊：

字典本身可配置——产品/运营会随时新增字典项
多语言字段动态——今天支持中英，明天加日韩西
菜单层级深——一级菜单/二级菜单都要翻译
跨业务共享——同一个字典被多个模块用

这种场景下"加 _en 字段"会导致：

1

status_zh, status_en, status_ja, status_ko, status_es, ...

字段无限增长——根本没法管。

二、方案 1：i18n 副表

最常见的做法——主表存核心数据，副表存翻译：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


CREATE TABLE dict_item (
 id BIGINT PRIMARY KEY,
 type VARCHAR(50), -- order_status / product_type ...
 code VARCHAR(50), -- PAID / SHIPPED ...
 sort INT,
 enabled BOOLEAN,
 UNIQUE KEY uk_type_code (type, code)
);

CREATE TABLE dict_item_i18n (
 id BIGINT PRIMARY KEY,
 dict_item_id BIGINT,
 locale VARCHAR(10), -- zh-CN / en-US / ja-JP / ...
 label VARCHAR(255), -- 翻译后的名称
 description VARCHAR(500), -- 翻译后的描述
 UNIQUE KEY uk_item_locale (dict_item_id, locale)
);

查询时 JOIN：

1
2
3
4
5


SELECT i.code, t.label
FROM dict_item i
LEFT JOIN dict_item_i18n t ON t.dict_item_id = i.id AND t.locale = ?
WHERE i.type = 'order_status' AND i.enabled = TRUE
ORDER BY i.sort;

优点

加新语言只增数据不改 schema
字典项本身和翻译解耦
易于配后台管理

缺点

每次查都 JOIN——大量字典查询有性能开销
缺少某语言时 fallback 要自己处理

Fallback 策略

请求 locale = ja-JP，但只有 zh-CN 和 en-US 翻译——怎么办？两种策略：

回退到默认语言（通常是 en-US）——返回英文
回退到 code 本身——比如返回 “PAID”

1
2
3
4
5
6
7
8


SELECT i.code,
 COALESCE(
 t.label,
 (SELECT label FROM dict_item_i18n WHERE dict_item_id = i.id AND locale = 'en-US'),
 i.code
 ) AS label
FROM dict_item i
LEFT JOIN dict_item_i18n t ON t.dict_item_id = i.id AND t.locale = ?

三、方案 2：JSON 字段

主表用 JSON 字段存所有语言：

1
2
3
4
5
6
7


CREATE TABLE dict_item (
 id BIGINT PRIMARY KEY,
 type VARCHAR(50),
 code VARCHAR(50),
 labels JSON, -- {"zh-CN": "已付款", "en-US": "Paid", "ja-JP": "支払済み"}
 sort INT
);

查询：

1
2


SELECT code, JSON_EXTRACT(labels, '$."zh-CN"') AS label
FROM dict_item WHERE type = 'order_status';

优点

不用 JOIN，单表查询快
schema 极简
取数据时一次拿到所有语言

缺点

JSON 字段查询/索引能力差
后台编辑更新某个语言要 JSON 操作
字典量大时 JSON 体积膨胀

适合字典量不大、改动不频繁的场景。

四、方案 3：消息文件 + DB 关联

把翻译完全放在配置文件（properties / yaml）里：

1
2
3
4
5


# messages_zh_CN.properties
dict.order_status.PAID=已付款
dict.order_status.SHIPPED=已发货

dict.product_type.SAAS=SaaS 服务

1
2
3


# messages_en_US.properties
dict.order_status.PAID=Paid
dict.order_status.SHIPPED=Shipped

DB 只存 code，业务里用 MessageSource 翻译：

1
2
3
4
5
6
7
8


@Autowired private MessageSource messageSource;

public String getLabel(String type, String code, Locale locale) {
 return messageSource.getMessage(
 "dict." + type + "." + code,
 null, code, locale
 );
}

优点

走标准 Spring i18n——成熟可靠
文件易于版本管理
性能极好（启动时全加载到内存）

缺点

不能在后台动态改翻译——必须发版
配置文件长了不好维护
多语言文件容易忘改

适合翻译相对稳定的场景——但是少数。多数业务希望运营能自己改翻译，这种方案不行。

五、推荐：副表 + 多级缓存

对一个生产级国际化系统，我推荐这套架构：

flowchart LR
 Client[前端] --> Cache1[CDN 缓存]
 Cache1 --> API[API 网关]
 API --> AppCache[应用本地缓存
Caffeine]
 AppCache --> RedisCache[(Redis)]
 RedisCache --> DB[(主表 + i18n 副表)]
 Admin[管理后台] -.改翻译.-> DB
 Admin -.触发刷新.-> RedisCache
 RedisCache -.广播失效.-> AppCache

设计要点：

DB 用副表方案（方案 1）
Redis 缓存全量字典——几 MB 数据，启动加载
应用本地 Caffeine 缓存——避免每次查 Redis
管理后台改翻译时主动失效缓存——所有实例同步刷新（用 Redis pub/sub 或 MQ）
前端 Service Worker / CDN 缓存按 locale 区分

六、菜单的国际化

菜单是另一个棘手场景——菜单结构是动态的，每个用户看到的菜单可能不同：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


CREATE TABLE menu (
 id BIGINT PRIMARY KEY,
 code VARCHAR(100) UNIQUE,
 parent_code VARCHAR(100),
 icon VARCHAR(100),
 path VARCHAR(255),
 sort INT,
 permission VARCHAR(100),
 enabled BOOLEAN
);

CREATE TABLE menu_i18n (
 menu_id BIGINT,
 locale VARCHAR(10),
 title VARCHAR(255),
 PRIMARY KEY (menu_id, locale)
);

查询：

1
2
3
4
5
6
7


SELECT m.id, m.code, m.parent_code, m.icon, m.path, m.sort,
 COALESCE(t.title, t_default.title, m.code) AS title
FROM menu m
LEFT JOIN menu_i18n t ON t.menu_id = m.id AND t.locale = ?
LEFT JOIN menu_i18n t_default ON t_default.menu_id = m.id AND t_default.locale = 'en-US'
WHERE m.enabled = TRUE
ORDER BY m.sort;

返回前端时已经是带翻译的菜单树——前端只需渲染。

七、错误消息的国际化

后端错误也要多语言——但错误信息往往动态：

1

throw new BusinessException("user_not_found", "User " + userId + " not found");

不能写死翻译——要用模板：

1
2
3


# messages_zh_CN.properties
error.user_not_found=用户 {0} 不存在
error.insufficient_balance=余额不足，需要 {0} 但只有 {1}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


public class I18nException extends RuntimeException {
 private final String code;
 private final Object[] args;

 public I18nException(String code, Object... args) {
 super(code);
 this.code = code;
 this.args = args;
 }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
 @Autowired private MessageSource messageSource;

 @ExceptionHandler(I18nException.class)
 public Result handle(I18nException e, Locale locale) {
 String msg = messageSource.getMessage(
 "error." + e.getCode(),
 e.getArgs(),
 "Unknown error",
 locale
 );
 return Result.fail(e.getCode(), msg);
 }
}

业务里：

1

throw new I18nException("user_not_found", userId);

八、Locale 的传递

前端怎么告诉后端"我要中文"？三种方式：

1. HTTP Header

1

Accept-Language: zh-CN, en;q=0.9

Spring 默认能识别。

2. URL 参数

1

GET /api/dict/order_status?locale=zh-CN

3. 用户偏好

用户登录后，从用户配置里读 locale——存在 user 表或 JWT claim 里。

1
2
3


LocaleResolver resolver = new SessionLocaleResolver();
// 或
LocaleResolver resolver = new AcceptHeaderLocaleResolver();

生产推荐：用户偏好优先 → URL 参数次之 → Header 兜底。

九、几个工程实践

1. 翻译流程标准化

研发 / 产品 / 翻译方的协作流程：

研发提交新字典项（默认中英两语）
翻译方在管理后台补其他语言
缓存自动刷新
上线前 review 是否所有 active 字典项都有翻译

2. 缺翻译的报警

定期跑一个脚本——任何 enabled 字典项缺少某种 locale 翻译就告警：

1
2
3
4
5
6


SELECT i.type, i.code
FROM dict_item i
WHERE i.enabled = TRUE
 AND NOT EXISTS (
 SELECT 1 FROM dict_item_i18n WHERE dict_item_id = i.id AND locale = 'en-US'
 );

3. 翻译质量保证

机器翻译只是初稿——专业翻译必须人工 review。某些行业术语机器翻得很离谱。

4. RTL 语言（阿拉伯语 / 希伯来语）

不只是文字翻译——整个 UI 要从右到左。CSS 用 dir="rtl" 切换。

5. 数字 / 日期 / 货币本地化

1
2
3
4


NumberFormat.getCurrencyInstance(locale).format(123456.78);
// zh-CN: ¥123,456.78
// en-US: $123,456.78
// de-DE: 123.456,78 €

不要自己写——用 ICU / java.text 标准库。

6. 时区

不同 locale 通常配不同时区——时间字段统一存 UTC，展示时按用户 timezone 转换。

十、常见踩坑

1. 把 locale 和 currency 混淆

zh-CN 是 locale，CNY 是 currency——两个完全独立的概念。中国大陆用户也可能想看 USD 报价。

2. 字典项加了但缓存没刷新

新加 dict_item 后必须主动失效缓存——否则要等 Redis TTL 到才能看到。

3. 字典 ID 和 code 都泄漏

返回前端时——只用 code，不要把 ID 暴露。后端内部关联用 ID，前端展示用 code。

4. 移动端 / Web 缓存策略不一致

移动 App 缓存了字典，Web 没缓存——改翻译后 App 用户要等很久才看到。要么 App 也定期同步，要么强制版本检查。

5. SEO 友好

国际化网站——每种语言一个 URL 路径（/zh-cn/... 和 /en-us/...）——而不是用同一个 URL 切换语言。这样搜索引擎能正确索引。

小结

把全文压一句：

后台系统的国际化不是『前端 i18n 文件』那么简单——数据字典、菜单、错误消息这些"动态文本"需要一套完整的『DB + 缓存 + 标准协议』方案。

工程要点：

数据字典用 i18n 副表 + 缓存
菜单同样的姿势
错误消息用 MessageSource + 占位符
缓存改时主动失效
缺翻译要监控告警
locale ≠ currency ≠ timezone，三者独立

把这些做对，你的系统能真正承载"出海到任意国家"——而不只是"加个英文翻译"。

Spring Boot 3 与 Spring 6 的变化与迁移

Tue, 17 Jun 2025 16:00:00 +0800

写在前面

Spring Boot 3.0 / Spring 6.0 在 2022 年 11 月发布，是 Spring 自 Spring 4.0 以来最大的一次跃迁。它不只是版本号 +1——而是整个技术栈的重新对齐：

Java 17 是最低基线——告别 Java 8/11
从 javax 到 jakarta——命名空间彻底切换
GraalVM 原生镜像支持——启动时间从秒级到毫秒级
内置 Observability——Micrometer + OTel
Servlet 6.0 / Jakarta EE 10

本文讲清楚这些变化、为什么这么变、升级要踩什么坑、什么场景该升、什么场景缓一缓。

一、最大的变化：javax → jakarta

这是最容易踩的坑——所有从 javax. 开始的标准库包名都改成了 jakarta.：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// Spring Boot 2.x
import javax.servlet.http.HttpServletRequest;
import javax.persistence.Entity;
import javax.validation.constraints.NotNull;
import javax.annotation.Resource;

// Spring Boot 3.x
import jakarta.servlet.http.HttpServletRequest;
import jakarta.persistence.Entity;
import jakarta.validation.constraints.NotNull;
import jakarta.annotation.Resource;

为什么改

Java EE 在 2017 年捐给 Eclipse 基金会成为 Jakarta EE。2019 年 Oracle 正式禁止 Eclipse 在新版本中继续使用 javax.*——所以从 Jakarta EE 9 开始全部改成 jakarta.*。Spring 6 跟着改。

升级痛点

依赖的第三方库要全是 Jakarta 兼容版本——MyBatis、Hibernate、Druid、各种 starter 都要升级
大量 import 要批量替换——IDE 有自动迁移工具，但要 review
老的 javax 库没升级 → 直接编译失败

如果项目里有依赖仍在用 javax——升 Spring Boot 3 之前必须先确认所有依赖都有兼容版本。

二、Java 17 最低基线

Spring Boot 3 强制 Java 17+——告别 Java 8/11。

Java 17 给你的礼物

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


// Records（数据载体）
public record UserDTO(Long id, String name, Integer age) {}

// Sealed classes
public sealed interface Shape permits Circle, Square {}

// Pattern matching for instanceof
if (obj instanceof String s && s.length() > 5) { ... }

// Switch expressions
String result = switch (status) {
 case "A" -> "Active";
 case "I" -> "Inactive";
 default -> "Unknown";
};

// Text blocks（多行字符串）
String json = """
 {
 "name": "test",
 "age": 30
 }
 """;

这些特性早几年就有，但Spring Boot 3 让你必须用 Java 17——团队终于有理由全员升级。

升级痛点

Java 8/11 的 build 脚本要改
某些第三方库（特别是字节码操作类）要升级——CGLIB、ASM、Lombok 等
JVM 参数有变化——某些 Java 8 时代的参数被废除

三、原生镜像：启动速度的革命

Spring Boot 3 内置 GraalVM 原生镜像支持——把 JVM 应用编译成单个原生二进制：

1
2


./mvnw native:compile
./target/myapp # 启动！

性能对比

	标准 JVM	原生镜像
启动时间	5-30 秒	30-100ms
内存占用	200-500 MB	30-80 MB
峰值性能	高（JIT 优化）	中（AOT 编译）
编译时间	秒级	几分钟
镜像体积	JAR + JDK	单二进制

适用场景

Serverless / FaaS——冷启动毫秒级，函数计算成本大降
CLI 工具
K8s 短生命周期 Pod
资源受限环境

不适合

峰值性能敏感——AOT 编译没 JIT 优化空间
大量动态特性（反射、动态代理）——需要额外配置元数据
依赖很多的项目——编译时间长得受不了

GraalVM 是杀手锏但不是银弹——多数业务系统暂时不需要。

四、Observability 一等公民

Spring Boot 3 把可观测性提到了前所未有的高度——内置 Micrometer Observation API：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Bean
public ObservedAspect observedAspect(ObservationRegistry registry) {
 return new ObservedAspect(registry);
}

@Service
public class OrderService {
 @Observed(name = "order.create")
 public Order create(OrderDTO dto) {
 // 自动产生 metrics + traces + logs
 }
}

@Observed 自动产出：

Metrics：Prometheus 抓取
Traces：OpenTelemetry 上报到 Tempo/Jaeger
Logs：结构化日志带 trace_id

统一的 Observability 模型——以前要分别配 Micrometer + Sleuth + 自定义 logger，现在一个注解搞定。

五、HTTP Interface：声明式 HTTP 客户端

Spring 6 引入声明式 HTTP 客户端——类似 Feign 但内置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public interface UserClient {
 @GetExchange("/users/{id}")
 User getById(@PathVariable Long id);

 @PostExchange("/users")
 User create(@RequestBody UserDTO dto);
}

@Bean
public UserClient userClient(WebClient.Builder builder) {
 HttpServiceProxyFactory factory = HttpServiceProxyFactory
 .builderFor(WebClientAdapter.create(builder.baseUrl("https://api.com").build()))
 .build();
 return factory.createClient(UserClient.class);
}

不需要再引 Feign——官方原生支持。

六、Problem Details (RFC 7807)

错误响应标准化——返回 application/problem+json：

1
2
3
4
5
6
7


{
 "type": "https://example.com/probs/insufficient-balance",
 "title": "Insufficient balance",
 "status": 400,
 "detail": "Balance is 100, required 500",
 "instance": "/orders/12345"
}

1
2
3
4
5
6


@ExceptionHandler(InsufficientBalanceException.class)
public ProblemDetail handle(InsufficientBalanceException e) {
 ProblemDetail pd = ProblemDetail.forStatusAndDetail(BAD_REQUEST, e.getMessage());
 pd.setType(URI.create("https://example.com/probs/insufficient-balance"));
 return pd;
}

业内标准——前端能用统一姿势处理。

七、虚拟线程（Spring Boot 3.2+）

JDK 21 GA 了虚拟线程——Spring Boot 3.2+ 一键启用：

1
2
3
4


spring:
 threads:
 virtual:
 enabled: true

效果：

Tomcat 每个请求一个虚拟线程
阻塞 IO 不再占用 OS 线程
传统 MVC 风格代码 + 虚拟线程 = WebFlux 的吞吐

很多人会问"还要不要 WebFlux？"——虚拟线程让传统 MVC 代码用接近 WebFlux 的吞吐量服务高并发，且没学习曲线。WebFlux 的位置开始变窄。

八、其他变化清单

删除 Java 8 / 11 支持
删除 Spring MVC 老的 path matcher（默认走 PathPattern）
新的 PropertyResolver
CRaC（Coordinated Restore at Checkpoint）：JVM 状态快照恢复，再降启动时间
HTTP/2 H2C 支持改进
AOT 编译预处理
更好的 SQL DSL（Spring Data 改进）

九、升级实战清单

评估期

列出所有依赖，确认全部有 Spring Boot 3 / Jakarta 兼容版本
确认 Java 17+ 在所有环境（dev、test、prod、CI）可用
评估 javax → jakarta 替换工作量
检查是否用了将被废弃的 API（如 WebSecurityConfigurerAdapter）

升级期

升 JDK 到 17（独立做，验证业务正常）
批量替换 javax → jakarta（IDE 工具或 OpenRewrite）
升 Spring Boot 3.0 → 3.x 最新版
升所有第三方依赖到 Jakarta 兼容版
修编译错误 + 测试
Spring Security 改为新 SecurityFilterChain 写法
开启 Observability 替换老的 Sleuth

验证期

全量回归测试
性能基准比对（启动时间、内存、QPS）
灰度发布

迁移工具

OpenRewrite：github.com/openrewrite/rewrite-spring 自动改大部分代码
Spring Boot Migrator：官方工具
IntelliJ IDEA：内置 jakarta 替换重构

十、什么场景该升 / 什么场景缓一缓

✅ 应该升

新项目——直接用 3.x，不要从 2.x 起步
JDK 已经在 17+——升级成本最小
想用虚拟线程 / 原生镜像
Spring Boot 2.7 已无 OSS 支持（OSS 支持已于 2023 年 11 月结束，商业扩展支持也已于 2025 年 8 月结束）

⏳ 缓一缓

依赖中有大量未升级的 javax 库
JDK 还卡在 8/11 升不上去
业务系统稳定，没有强需求
团队没人有时间做迁移测试

绝大多数项目应该启动迁移——Spring Boot 2.7 的 OSS 支持已于 2023 年 11 月结束，商业扩展支持也已于 2025 年 8 月结束，再不升就完全没有安全更新了。

十一、Spring Boot 2 → 3 的几个真实坑

1. JPA 用了 `javax.persistence.GenerationType` 等

全局替换 import。

2. Spring Security 配置类

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 2.x
public class SecurityConfig extends WebSecurityConfigurerAdapter {
 @Override
 protected void configure(HttpSecurity http) throws Exception { ... }
}

// 3.x
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 return http...build();
}

WebSecurityConfigurerAdapter 在 3.x 完全删除——所有项目都要重写 Security 配置。

3. SwaggerUI（springdoc-openapi）

要从 1.x 升 2.x——配置完全重写。

4. Spring Cloud 版本对应

Spring Boot 3 不能用 Spring Cloud 2021.0（仍是 javax）。对应关系按 Boot 小版本严格区分：

Spring Boot	Spring Cloud
3.0.x / 3.1.x	2022.0.x（Kilburn）
3.2.x	2023.0.x（Leyton）
3.3.x / 3.4.x	2023.0.x 或 2024.0.x（Moorgate）
3.5.x	2025.0.x（Northfields）

踩坑提醒：跨大版本配错（如 Boot 3.4+ 配 2022.0.x）会出现 starter 缺失、CVE 不修等问题。升 Boot 时务必参照 Spring Cloud Supported Versions 同步升 Cloud。

5. MyBatis-Plus

需要 3.5.3+——更老的版本不兼容 Spring Boot 3。

6. Lombok

要 1.18.24+——老版本可能编译不过。

小结

把全文压一句：

Spring Boot 3 是 Spring 生态进入 Jakarta + Java 17 + 原生镜像 + Observability 时代的入场券——不是小升级，是范式转移。

工程实践：

新项目优先用 3.x
老项目要规划迁移——拖到 2.7 EOL 就被动了
Java 17+ 是基线，不可回避
OpenRewrite 自动迁移省掉 80% 体力活
虚拟线程让传统 MVC 写法逼近 WebFlux 吞吐

升 Spring Boot 3 不是"为了升而升"——是 Java 服务端走向下一个十年的必经之路。

软件研发生命周期中的核心文档梳理

Tue, 06 May 2025 17:48:31 +0800

软件研发生命周期中的核心文档梳理

在软件研发项目的全流程中，文档是一项不可或缺的支撑工具。它们不仅仅是“凭证”，更是团队协作、需求澄清、技术落地、交付和维护的重要桥梁。对于管理者、产品、开发、测试乃至运维等不同角色，理解并正确使用每类文档，能有效提升项目的效率和质量。本文将对研发生命周期各阶段的主流文档进行梳理，着重说明其主要作用、使用场景和典型使用角色。

1. 项目启动与可行性分析阶段

1.1 项目建议书/立项文档

主要作用：明确项目背景、预期目标和价值，论证开展该项目的合理性和必要性。
使用场景：项目正式启动前，项目申报、资源争取、重大决策时。
典型角色：项目负责人、高管、产品经理、业务方。

模板文件：查看项目建议书模板

1.2 可行性分析报告（可选）

主要作用：多维度分析项目在技术、经济、资源、合规等方面的可行性与主要风险。
使用场景：创新性较强、规模较大的项目立项评审阶段。
典型角色：架构师、技术负责人、项目管理。

模板文件：查看可行性分析报告模板

2. 需求分析阶段

2.1 业务需求文档/需求调研报告

主要作用：全面记录用户实际业务流程、关键需求与问题点，从业务视角定义系统边界。
使用场景：需求调研、业务梳理、需求评审前期。
典型角色：业务分析师、产品经理、客户代表。

模板文件：查看业务需求文档模板

2.2 软件需求规格说明书（SRS）

主要作用：作为开发、测试、验收等一切后续工作的正式依据，将功能与非功能需求精确落地。
使用场景：需求评审、开发前需求冻结、变更管理、测试验收。
典型角色：产品经理、开发、测试、项目管理。

模板文件：查看软件需求规格说明书模板

2.3 原型图 / 交互设计文档（可选）

主要作用：通过界面视觉化，帮助各方对齐功能预期和操作流程，提高需求沟通效率。
使用场景：需求澄清、界面评审、前后端协作。
典型角色：产品经理、UI/UX设计师、开发、测试。

模板文件：查看原型图/交互设计文档模板

3. 设计阶段

3.1 概要设计说明书（High-Level Design, HLD）

主要作用：定义系统总体架构、模块划分、主要逻辑流程和关键技术选型，为详细设计和开发奠定基础。
使用场景：设计方案评审、团队分工、技术决策。
典型角色：架构师、技术负责人、开发主程、项目经理。

模板文件：查看概要设计说明书模板

3.2 详细设计说明书（Low-Level Design, LLD）

主要作用：细致描述各个模块/功能的实现细节，包括数据结构、接口、核心算法和异常处理，为具体编码提供指引。
使用场景：开发任务分解、代码编写前、Code Review。
典型角色：开发主程、开发工程师、测试人员、架构师。

模板文件：查看详细设计说明书模板

4. 实现与测试阶段

4.1 测试用例说明书 / 测试计划

主要作用：明确验证每一条需求和功能点的具体方式，涵盖正常/异常流程与边界场景。
使用场景：测试设计、开发自测、回归测试、验收测试。
典型角色：测试工程师、开发自测、产品经理。

模板文件：查看测试计划模板

4.2 测试报告

主要作用：汇总测试执行结果与缺陷情况，为产品发布与质量判断提供依据。
使用场景：测试完成后、阶段性评审、最终上线决策。
典型角色：测试工程师、项目经理、开发负责人。

模板文件：查看测试报告模板

5. 上线与运维阶段

5.1 发布手册/上线方案

主要作用：规范发布流程，明确上线操作步骤、注意事项、回滚与应急措施。
使用场景：系统上线、版本发布、运维流程梳理。
典型角色：运维工程师、开发、实施人员。

模板文件：查看发布手册/上线方案模板

5.2 用户手册/操作说明

主要作用：指导终端用户或业务方规范使用系统，降低培训和支持成本。
使用场景：新系统推广、用户培训、客户支持。
典型角色：产品经理、技术支持、终端用户。

模板文件：查看用户手册/操作说明模板

5.3 运维手册/技术支持文档

主要作用：梳理系统部署、监控、常见故障排查和恢复流程。
使用场景：系统上线运维、快速排障、知识传承。
典型角色：运维工程师、技术支持、开发团队。

模板文件：查看运维手册/技术支持文档模板

结语

文档贯穿软件研发全流程，不同文档的侧重点各有不同，针对的使用场景和主要角色也各异。正确理解和高效利用这些文档，有助于团队协作、信息传递和项目质量管控。不论项目大小，适度、规范、持续更新的文档体系，都是实现高质量交付与维护的关键保障。

扫码登录的完整设计

Fri, 21 Feb 2025 15:30:00 +0800

写在前面

PC 浏览器扫手机端二维码自动登录——12306、知乎、京东、网易邮箱、微信网页版……这种交互在国内已经是标配。

它看着简单——但背后是一套涉及前端轮询、后端状态机、长连接、安全控制的完整设计。新人接这块时常常忽略关键细节，做出来要么不安全、要么体验差。

本文从协议、状态机、API 设计、安全考虑几个层面把扫码登录讲清楚。

一、整体流程

sequenceDiagram
 participant Browser as PC 浏览器
 participant Server as 后端
 participant Phone as 手机 App

 Browser->>Server: GET /qr/create
 Server->>Server: 生成 sceneId + 二维码
 Server-->>Browser: { sceneId, qrUrl, expiresIn }
 Browser->>Browser: 展示二维码
 Browser->>Server: 长轮询 / SSE 等待状态
 Phone->>Phone: 扫描二维码
 Phone->>Server: POST /qr/scan { sceneId, token }
 Server->>Server: 标记 sceneId 为 SCANNED
 Server-->>Browser: SCANNED（手机已扫，等确认）
 Phone->>Server: POST /qr/confirm { sceneId, token }
 Server->>Server: 标记 sceneId 为 CONFIRMED + 颁发 PC 端 token
 Server-->>Browser: CONFIRMED + token
 Browser->>Browser: 设置 cookie/storage 跳转登录页

四个核心环节：

PC 请求二维码
手机扫描（标记 sceneId 状态变化）
手机确认登录（颁发 PC 端 token）
PC 拿到 token 完成登录

二、状态机

sceneId 是整个流程的核心标识——它在后端经历几个状态：

stateDiagram-v2
 [*] --> PENDING: 创建二维码
 PENDING --> SCANNED: 手机扫描
 SCANNED --> CONFIRMED: 手机确认
 SCANNED --> CANCELLED: 手机取消
 PENDING --> EXPIRED: 超时
 SCANNED --> EXPIRED: 超时
 CONFIRMED --> [*]: PC 拿到 token
 CANCELLED --> [*]
 EXPIRED --> [*]

为什么"扫描"和"确认"要分两步？

手机扫到的是任意二维码，不一定是登录用的——必须显式确认才算同意登录
防止"路边贴的恶意二维码骗你扫"——扫描后用户能看到"是否登录到 xxx 网站"的确认页

存储用 Redis 自然——key 是 sceneId，value 是 status + 关联数据，TTL 5 分钟。

三、API 设计

1. 创建二维码

1
2


GET /api/qr/create
Response: { sceneId, qrPayload, expireSeconds }

qrPayload 是二维码内容——通常包含：

1

https://your-app.com/qrlogin?scene=<sceneId>&t=<timestamp>&sign=<signature>

带签名防止伪造——后端校验签名才允许处理。

2. PC 端轮询/订阅状态

方式 A：长轮询

1
2


GET /api/qr/wait?sceneId=xxx&from=PENDING
（后端阻塞，直到状态变化或 30 秒超时返回）

PC 端循环调用，每次带上"我现在知道的状态"——后端只在状态变化时返回。

方式 B：SSE（推荐）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


GET /api/qr/stream?sceneId=xxx
Accept: text/event-stream

event: status
data: {"status": "PENDING"}

event: status
data: {"status": "SCANNED"}

event: status
data: {"status": "CONFIRMED", "token": "..."}

SSE 比长轮询省连接、省服务端线程，强烈推荐。

方式 C：WebSocket

适合"长连接 + 双向通信"场景——但做扫码登录是杀鸡用牛刀。

3. 手机扫描

1
2
3


POST /api/qr/scan
Body: { sceneId }
Headers: Authorization: Bearer <user_token>

手机已登录用户扫码后，App 调这个接口——后端把 sceneId 标记 SCANNED，记录是哪个 user 扫的。

返回内容包括"PC 端要登录哪个账号"信息，让 App 显示二次确认页面：

1
2


是否使用账号 zhangsan@example.com 登录到 PC 端？
[确认] [取消]

4. 手机确认

1
2


POST /api/qr/confirm
Body: { sceneId }

后端：

校验 sceneId 状态是 SCANNED
校验当前 user 和扫描时的 user 一致
颁发 PC 端 token
把 sceneId 状态改为 CONFIRMED + 关联 token

PC 端的 SSE 收到 CONFIRMED 状态 + token，完成登录。

5. 手机取消

1
2


POST /api/qr/cancel
Body: { sceneId }

把 sceneId 状态改为 CANCELLED——PC 端收到通知后展示"已取消"。

四、安全考虑

扫码登录是登录入口——安全比体验更重要。

1. sceneId 必须不可猜

用 UUID v4 或 nanoid——不要用自增 ID。攻击者枚举 sceneId 可能尝试劫持别人的登录会话。

2. 二维码 URL 带签名

1

https://app.com/qrlogin?scene=xxx&t=1700000000&sign=hmac(secret, scene+t)

App 扫码后先校验签名——拒绝伪造的二维码。

3. PC 端和手机要校验"会话一致性"

PC 端轮询时带一个浏览器随机 token——手机确认时如果发现 token 不一致，说明可能被中间人劫持。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


PC: GET /qr/create
 Browser生成 browserNonce 存 cookie
 qrPayload 中包含 browserNonce 的 hash

Phone: 扫码后 POST /qr/scan
 后端记录 nonce hash

PC: GET /qr/stream
 带上 browserNonce
 后端校验 nonce hash 一致才返回 token

4. 二维码必须短时间过期

5 分钟内不被扫描就 EXPIRED——避免有人贴在公共场所"骗扫"。

5. 已扫描状态也要超时

SCANNED 状态如果 1 分钟内没确认 → EXPIRED——避免"用户扫了但没确认就走了，攻击者后续接管"。

6. 手机端必须已登录

扫描接口要求用户已登录——不允许游客状态扫码。否则任何人扫了都能"以游客身份登录 PC 端"，毫无意义。

7. 防 CSRF

PC 端的 sceneId 是会话级的——一个 sceneId 只能绑定一个浏览器 session。换浏览器轮询同一个 sceneId 应该被拒绝。

8. 异地登录提醒

PC 端登录成功后发送邮件/短信通知用户——异地登录是常见的"安全感"配置。

五、UX 上的几个细节

1. 扫描后的状态展示

UX 不要只显示"等待扫描"和"登录成功"——SCANNED 状态要专门展示：

1
2
3


[二维码图] [二维码灰色 + 中央对勾] [跳转中...]

请扫码登录 扫描成功，请在手机上确认 登录成功

让用户知道"手机端在做什么"，不会以为系统卡住。

2. 二维码刷新

5 分钟过期后自动刷新——而不是显示"过期请重新打开"。

3. 手机和 PC 一定不能在同一浏览器

PC 浏览器扫描 PC 浏览器二维码——必须拒绝。手机端 App 才有资格扫——通过 User-Agent 简单判断。

4. 取消的反馈

用户在手机上"取消"后——PC 应该立刻看到"已取消"，并提供"重新生成二维码"按钮。

六、技术实现要点

1. SSE 比长轮询好

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


const evt = new EventSource(`/api/qr/stream?sceneId=${sceneId}`);
evt.addEventListener('status', e => {
 const data = JSON.parse(e.data);
 if (data.status === 'CONFIRMED') {
 localStorage.setItem('token', data.token);
 location.href = '/dashboard';
 evt.close();
 }
});
evt.onerror = () => {
 // 重连
};

记得在 nginx 配置 proxy_buffering off，否则消息要等 buffer 满才推送。

2. 后端用 Redis 维护状态

1
2
3


String sceneId = UUID.randomUUID().toString();
SceneState state = new SceneState("PENDING", null, System.currentTimeMillis());
redis.setex("qr:" + sceneId, 300, JSON.toJSONString(state));

状态变更用 Lua 脚本保证原子性：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


local key = KEYS[1]
local expectStatus = ARGV[1]
local newStatus = ARGV[2]
local current = redis.call('GET', key)
if current == false then return -1 end
local state = cjson.decode(current)
if state.status ~= expectStatus then return 0 end
state.status = newStatus
redis.call('SETEX', key, 300, cjson.encode(state))
return 1

3. 跨进程通信

后端可能多实例——手机端命中实例 A，PC 端命中实例 B。状态变更需要广播：

简单：后端只读 Redis 状态——所有实例数据一致
进阶：用 Redis Pub/Sub 主动推送实例 B 触发 SSE

4. 二维码生成

后端不一定要生成图片——返回二维码内容字符串，前端用 qrcode.js 渲染：

1
2


import QRCode from 'qrcode';
QRCode.toCanvas(canvasEl, qrPayload);

省了后端 PNG 编码、节省带宽。

七、移动 App 端的实现要点

1. 调用系统相机扫码

iOS / Android 都有原生 API——读取二维码内容。

2. 内容解析

1
2
3
4
5
6
7
8


// 二维码内容
https://app.com/qrlogin?scene=abc&t=...&sign=...

// App 端：
- 校验是不是自家域名
- 校验签名
- 校验时间（防重放）
- 调用 /qr/scan 接口

如果二维码不是自家——不要打开浏览器跳转 URL，那等于把扫码结果给到不可信的网站。

3. 显示确认页面

不要扫描后直接跳过——展示明确的"是否登录到 PC？“对话框，用户主动点确认才下一步。

4. 异常处理

网络断开 → 提示重试
二维码过期 → 提示用户刷新 PC 端
重复扫描 → 提示"该二维码已被扫描”

八、扩展场景

1. 关注公众号即登录（微信）

二维码生成时带上"场景值"——用户扫码并关注公众号后，公众号收到事件回调——等同于"扫描+确认"一次完成。

适合"既要登录又要涨粉"的场景。

2. 跨端会话同步

PC 扫码登录后，手机端是不是也算"已登录"？ 通常是——扫码本身就证明了用户身份。

3. 桌面客户端扫码

很多桌面 App（如 Microsoft Teams、Slack）也支持二维码登录——逻辑和 Web 完全相同。

4. 离线扫码

部分场景下手机断网时扫描——可以先在本地校验签名 + 缓存意图，联网后再上报后端。

小结

把全文压一句：

扫码登录的核心是『二维码 + sceneId + 状态机 + 双端协同』——看似 5 分钟能写完，做对要考虑安全、体验、跨实例同步十几个点。

工程要点：

状态机：PENDING → SCANNED → CONFIRMED——不要跳过 SCANNED
二维码 URL 带签名
PC 端用 SSE 等状态变化
手机端必须已登录 + 显式确认
sceneId UUID + 短期 TTL
跨实例用 Redis 共享状态

掌握这套，你做的"扫码登录"在体验和安全上能直接对标主流产品。

浅谈 Raft：让分布式一致性变可理解的算法

Sun, 15 Dec 2024 15:30:00 +0800

写在前面

分布式系统里"多个节点对一件事达成一致"听起来简单，做对极难——这就是**共识算法（Consensus）**要解决的问题。

最经典的共识算法是 Paxos——Lamport 1998 年的论文。但 Paxos 论文有个臭名昭著的问题：没人看得懂。Lamport 后来又写了"Paxos Made Simple"试图解释——还是难懂。

2014 年 Stanford 的 Diego Ongaro 和 John Ousterhout 提出了 Raft 算法——明确目标是"可理解性优先"。论文标题就是 In Search of an Understandable Consensus Algorithm。

Raft 现在是工业界事实标准——etcd、Consul、TiKV、CockroachDB、HashiCorp 全家桶都在用。本文用直觉的方式把 Raft 讲清楚——不写公式，但讲清核心机制和工程意义。

一、共识算法在解决什么问题

设想 5 台机器要一起维护一份日志：

1
2
3
4
5


Machine 1: [A, B, C, D]
Machine 2: [A, B, C, ?]
Machine 3: [A, B, C, D, E]
Machine 4: [A, B, ?, ?]
Machine 5: [A, B, C, D]

某些机器宕机、网络分区、消息延迟——怎么保证所有活着的机器最终都看到同一份日志？

共识算法要保证：

Safety（安全性）：即使发生故障，所有节点的状态不会冲突
Liveness（活性）：只要多数节点存活，系统能继续工作
Consistency（一致性）：相同输入序列产生相同输出

Raft 用三个核心机制实现这些性质——领导选举、日志复制、安全性。

二、Raft 的角色

集群里每个节点处于三种状态之一：

Leader：唯一的"指挥官"，处理所有客户端请求
Follower：被动响应 Leader 和 Candidate 的消息
Candidate：选举期间的临时角色

flowchart LR
 Follower -->|超时未收到心跳| Candidate
 Candidate -->|获得多数票| Leader
 Candidate -->|发现已有 Leader| Follower
 Leader -->|发现更高 term| Follower

任何时刻只有一个 Leader——这是 Raft 简化的关键。所有写入都通过 Leader——Leader 把变更复制到 Followers——Follower 投票确认——Leader 提交并通知所有人。

三、领导选举

集群启动时所有节点都是 Follower。每个节点有一个随机选举超时（150-300ms）：

Follower 在超时内没收到 Leader 心跳 → 转为 Candidate
Candidate 给自己投一票，向其他节点发送"选我"请求
其他节点收到后：
- 如果当前 term 没投过票 → 投票给它
- 如果已投过票 → 拒绝
Candidate 收到多数票（n/2+1）→ 成为 Leader
新 Leader 立刻发心跳，宣告自己存在

sequenceDiagram
 Note over Node1,Node5: 所有 Follower
 Node1-->>Node1: 选举超时
 Node1->>Node2: RequestVote (term=1)
 Node1->>Node3: RequestVote
 Node1->>Node4: RequestVote
 Node1->>Node5: RequestVote
 Node2-->>Node1: 投票 ✓
 Node3-->>Node1: 投票 ✓
 Note over Node1: 收到 3/5 票
 Note over Node1: 成为 Leader
 Node1->>Node2: 心跳
 Node1->>Node3: 心跳

为什么要随机超时

如果所有节点超时一致——所有节点同时变 Candidate，互相投票冲突，没人能赢。随机化让某个节点先到超时点——它最早开始拉票，更容易胜出。

Term 概念

Raft 把时间分成"任期"（Term）——每次选举触发新的 term。Term 是单调递增的整数。

Leader 每次发心跳带上自己的 term
Follower 收到更高 term → 降级、跟随新 Leader
旧 Leader 网络恢复后看到更高 term → 自动退位

Term 解决了"脑裂后旧 Leader 还以为自己是 Leader"的问题——所有响应都校验 term，更高 term 自动获胜。

四、日志复制

Leader 收到客户端写请求后：

写入自己的日志
并行发给所有 Follower（AppendEntries RPC）
多数 Follower 确认收到 → 提交（commit）
下次心跳通知 Follower 提交
提交后应用到状态机，回复客户端

sequenceDiagram
 Client->>Leader: write x=5
 Leader->>Leader: append log
 par
 Leader->>Follower1: AppendEntries
 Leader->>Follower2: AppendEntries
 Leader->>Follower3: AppendEntries
 Leader->>Follower4: AppendEntries
 end
 Follower1-->>Leader: ack
 Follower2-->>Leader: ack
 Follower3-->>Leader: ack
 Note over Leader: 收到 3/5 ack
 Leader->>Leader: commit
 Leader-->>Client: ok
 Leader->>Follower1: 下次心跳通知 commit

日志一致性

每条日志带上 (term, index)——Follower 收到 AppendEntries 时检查：

上一条日志的 (term, index) 和我本地的对得上吗？
对得上 → 追加新日志
对不上 → 拒绝，让 Leader 退一格再发

Leader 维护每个 Follower 的 nextIndex——发现 Follower 跟不上时逐步回退、重发，直到对齐。

五、安全性约束

光有选举和复制不够——必须保证已提交的日志永远不丢。Raft 通过几个约束实现：

1. 选举限制：只有"日志最新"的节点能赢

Candidate 拉票时附带自己最后一条日志的 (term, index)。Follower 只投票给"日志比自己新或一样新"的 Candidate。

这保证新 Leader 一定包含所有已提交的日志——不会有"新 Leader 上任后丢掉之前已提交的事"。

2. 提交限制：只能提交当前 term 的日志

Leader 不能直接提交"上一个 term 的日志"——只能等当前 term 有日志被多数复制后，带着把之前的日志一起提交。

这避免了一个微妙的 bug——Lamport 的 Paxos 也有类似机制，但 Raft 把它讲得更清楚。

3. AppendEntries 一致性检查

每次发日志都带上前一条日志的 (term, index)——Follower 检查匹配后才追加。这是一种简单粗暴但有效的对齐方式。

六、几个常见问题

1. 网络分区怎么办

5 节点集群被分成 [3, 2]：

3 节点的子集仍可选举出 Leader、继续对外服务（多数派）
2 节点子集无法选出新 Leader、只能等待

分区恢复后——2 节点子集发现更高 term，自动跟随大集群的 Leader。未提交的事务被覆盖。

2. Leader 故障

Leader 宕机后心跳停止——某个 Follower 选举超时变 Candidate——选出新 Leader——继续工作。通常 1-2 秒内完成切换。

3. 客户端读

朴素做法：所有读都走 Leader——保证强一致，但 Leader 压力大。

优化方案：

ReadIndex：读时让 Leader 确认自己仍是 Leader（一次心跳），然后本地读
Lease Read：Leader 持有"租约"，租约期内本地读
Follower Read：允许从 Follower 读（弱一致，但快）

4. 集群成员变更

加节点 / 减节点这种"在运行中变更集群配置"——Raft 用两阶段共识（Joint Consensus）：

先达成"新旧配置共存"的共识
再切到纯新配置

避免了"新旧多数派同时存在导致两个 Leader"的脑裂。

5. 日志压缩

日志一直涨会爆磁盘——Raft 用快照（Snapshot）：

周期性把状态机全量存盘
旧日志可以删除
新加入的节点先拉快照，再追日志

七、Raft 的工业实现

etcd

Kubernetes 的元数据存储——5 节点 Raft 集群最常见。高可用 + 强一致——但写性能不高（每次都要多数派 ack）。

Consul

HashiCorp 的服务发现——同样 5 节点 Raft。

TiKV

PingCAP 的分布式 KV——每个数据 region 独立 Raft——上千个 Raft 组并行。

CockroachDB

SQL 数据库底层用 Raft 复制每个 range。

Apache Ratis

通用 Raft 库（Java）——OZone、Apache Iceberg 等用它。

MIT 6.824 的 Lab

学 Raft 最好的方式是自己实现一遍——MIT 6.824 的 Lab 2A/2B/2C 就是手写 Raft。

八、Raft vs Paxos vs Multi-Paxos

	Paxos	Multi-Paxos	Raft
出处	Lamport 1998	同上扩展	Ongaro 2014
角色	Proposer/Acceptor/Learner	同上	Leader/Follower/Candidate
强 Leader	✗	✓	✓
可理解性	低	中	高
工业实现	Chubby 早期文献描述	Chubby / Spanner / Megastore	etcd / Consul / TiKV / 几乎所有新系统

关于 ZooKeeper：ZooKeeper 用的是 ZAB（ZooKeeper Atomic Broadcast）——不是 Multi-Paxos，而是一种 Paxos 变体，针对"主备复制 + 严格按序广播"做了简化。ZAB 和 Raft 的设计哲学接近（强 Leader + 心跳 + 单调递增的 epoch / term），但出现得更早，是 ZK 自家的方案。

Raft 在功能上和 Multi-Paxos 等价——但可理解性、可实现性、可调试性都强很多。这就是它后来居上的核心原因。

九、什么时候用 Raft、什么时候不用

✅ 适合：

需要强一致性的元数据存储（K8s 配置、服务发现）
数据库的元数据复制（schema、租约）
小规模集群（3-7 节点）
写入不频繁但要绝对可靠

❌ 不适合：

大规模数据复制（百 GB 数据）——延迟高
极高写入吞吐场景——多数派 ack 是瓶颈
跨数据中心——网络延迟让心跳和投票变得脆弱
AP 系统（如 Cassandra）——选 P + A 而不是 C，根本不需要共识

最低要 3 节点（容忍 1 个故障）、推荐 5 节点（容忍 2 个）——永远不要 1 节点 Raft，那等于没用。

十、对工程的启发

Raft 不只是"一个算法"——它示范了几个值得借鉴的工程哲学：

可理解性是设计目标——不只是"能 work"，要"能讲清"
强 Leader 简化系统——比起完全对称的 Paxos，单 Leader 让推理更容易
机制分离：选举、复制、安全性各自独立讲清楚
拒绝复杂特性：Raft 的论文明确说"拒绝任何不必要的复杂"

设计任何分布式系统时——理解 Raft 都是入门必修课。

小结

把全文压一句：

Raft 用『强 Leader + 多数派复制 + 严格安全约束』把分布式一致性讲得像故事——可理解性是它最大的成就，可工业化是它的最大遗产。

学习路径推荐：

读 Raft 论文：raft.github.io（强烈推荐）
看可视化：The Secret Lives of Data
手写实现：MIT 6.824 Lab 2
用一遍 etcd / Consul

掌握 Raft 后再看 ZooKeeper、ZAB、Spanner 的 Multi-Paxos——能立刻看出它们解决问题的相同与不同。

微服务之间，到底应如何传递用户信息

Fri, 08 Nov 2024 10:00:00 +0800

一个所有人都遇到过的场景

设想一个最常见的下单链路：

1
2


用户 → 网关 → 订单服务 → 库存服务 → 优惠券服务
 ↘ 消息队列 → 积分服务（异步）

订单服务要写 created_by，库存服务要校验"这个用户是不是有权操作这个仓库"，优惠券服务要判断"这张券是不是这个用户的"，积分服务在异步消费里要给"这个用户"加分。

四个服务，每一跳都要回答同一个问题：当前是谁在操作？

这件事看似简单，真做起来却处处是坑。下面我们就把"用户信息怎么在微服务之间传"这件事，从最朴素的做法一路讲到 Service Mesh，把每条路的优缺点摊开。

朴素做法：把用户信息当参数到处传

最直觉的做法——既然下游需要 userId，那就在接口签名里多加一个参数好了：

1
2
3


createOrder(userId, items, address)
deductStock(userId, skuId, count)
useCoupon(userId, couponId)

第一眼看着没问题，真用起来你会发现：

侵入性极强：业务接口里混进了和业务无关的"操作人"字段，函数签名越来越长。
极易出错：调用方写错一个 userId，相当于"以 A 的身份替 B 下单"，这是越权漏洞。
无法约束：下游服务无法判断这个 userId 是真是假，调用方说是谁就是谁。
新增字段成本爆炸：今天加个 tenantId，明天加个 traceId，所有接口都要改一轮。

所以这个方案在生产里几乎没人用。它给我们一个启示：用户上下文必须从业务参数里剥离出来，走专门的通道。

思路一：Token 全链路透传

既然用户登录后拿到了一个 Token（多数情况下是 JWT），最简单的"分布式做法"就是——把这个 Token 一路往下传，每个服务自己解析。

1
2


客户端 ──Token──▶ 网关 ──Token──▶ 订单 ──Token──▶ 库存
 ──Token──▶ 优惠券

它的好处很明显：

无状态：每个服务凭 Token 自证身份，不依赖中心节点。
解耦：服务之间不需要知道"上游是谁"，只看 Token。

但你很快会撞到这些问题：

重复解析：链路上每个服务都要解一遍 JWT，验签一遍。链路越长，重复劳动越多。
密钥与公钥的分发：每个服务都得拿到验签公钥，密钥轮换时所有服务都要同步更新。
Token 过期/撤销难：如果链路中段调用耗时较长，Token 在下游可能已经过期；用户登出后已经下发的 Token 也很难"召回"。
安全面被放大：原始 Token 流到了每一个内部服务，任何一个服务的日志泄漏，都等于泄漏了用户凭证。
服务间调用不天然带 Token：定时任务、MQ 消费、内部系统触发的调用，根本没有用户 Token，需要专门"造一个"。

所以纯粹的 Token 全链路透传，更适合小规模、链路短、对安全要求中等的场景，不适合作为大型系统的默认方案。

思路二（主线推荐）：网关剥离 + 上下文透传

这套思路的核心一句话——鉴权"做一次"，上下文"传一路"。

整体架构

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


 ┌─ 解析 Token
 ├─ 验签 / 校验过期
 网关 ───────┤
 ├─ 提取用户字段：userId / tenantId / roles
 └─ 写入下游请求头：X-User-Id / X-Tenant-Id ...

 ┌────────┐ ┌────────┐
 │ 订单 │ ──────▶ │ 库存 │
 └────────┘ └────────┘
 ↑读上下文 ↑读上下文

网关做唯一一次重活：验 Token、查黑名单、拉用户基本信息，然后把"必要的身份字段"以轻量请求头的形式写进下游请求。
下游服务不再信任原始 Token，只读那几个固定的请求头。

这个方案为什么好

重活只做一次：避免链路上重复解析。
下游零负担：业务服务不需要懂 JWT、不需要拿公钥，只关心"当前用户是谁"。
安全收敛：原始 Token 被拦在网关后面，不再扩散到内部。
上下文可扩展：今天传 userId，明天加个 tenantId、灰度标签、AB 实验分组——都只是多一个请求头的事。

一个绕不开的安全约束

下游服务"无脑信任"请求头，意味着——如果有人能绕过网关直接调用内部服务，他就能伪造任何身份。

所以这套方案有一个硬前提：

内部服务的入口必须封死，只接受来自网关或其他内部服务的流量。

实现手段可以是：内网网络隔离、Service Mesh 的 mTLS、内部调用专用的鉴权 Header（如服务间共享密钥），或者三者结合。这一步偷懒，整套体系就形同虚设。

服务内部：上下文如何"隐式"流转

网关把用户字段塞进了请求头，下游服务怎么用？最糟的写法是这样：

1
2
3
4
5
6
7
8
9


// 反面教材
public OrderVO createOrder(HttpServletRequest request, OrderDTO dto) {
 String userId = request.getHeader("X-User-Id");
 Order order = new Order();
 order.setCreatedBy(userId);
 stockClient.deduct(userId, dto.getSkuId(), dto.getCount()); // 手动透传
 couponClient.use(userId, dto.getCouponId()); // 手动透传
 // ...
}

每个业务方法都要从 request 里抠 header，每次调下游又要手动塞回去，这就是把"基础设施的事"塞进了"业务代码"。

正确的做法是建一个用户上下文容器，让请求头进来时自动入，调下游时自动出，业务代码完全无感。

接收侧：入口拦截器

在服务最外层装一个拦截器（不同框架叫法不同：Filter、Interceptor、Middleware），统一做一件事：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


public class UserContextFilter implements Filter {

 @Override
 public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain)
 throws IOException, ServletException {
 HttpServletRequest request = (HttpServletRequest) req;

 UserContext ctx = UserContext.builder()
 .userId(request.getHeader("X-User-Id"))
 .tenantId(request.getHeader("X-Tenant-Id"))
 .roles(parseRoles(request.getHeader("X-User-Roles")))
 .build();

 UserContextHolder.set(ctx);
 try {
 chain.doFilter(req, resp);
 } finally {
 UserContextHolder.clear(); // 关键：必须清理，避免线程复用污染
 }
 }
}

业务代码里就只剩一句：

1

String userId = UserContextHolder.current().getUserId();

调用侧：出站拦截器

服务调用其他服务时，在 HTTP 客户端的拦截器里把上下文塞回请求头：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public class UserContextClientInterceptor implements ClientHttpRequestInterceptor {

 @Override
 public ClientHttpResponse intercept(HttpRequest request, byte[] body,
 ClientHttpRequestExecution execution) throws IOException {
 UserContext ctx = UserContextHolder.current();
 if (ctx != null) {
 request.getHeaders().add("X-User-Id", ctx.getUserId());
 request.getHeaders().add("X-Tenant-Id", ctx.getTenantId());
 }
 return execution.execute(request, body);
 }
}

这样业务代码写 stockClient.deduct(skuId, count)，框架自动把用户上下文带过去。

异步场景的坑

上下文容器一般基于"线程本地存储"实现。一旦发生线程切换，上下文就丢了：

把任务扔进线程池
用回调 / Future / 协程切换执行线程
定时任务由调度线程触发

解决思路是：在任务提交那一刻，把当前线程的上下文"拷贝一份"附在任务上；任务被新线程执行前，再把上下文恢复进去。Java 生态里阿里开源的 TransmittableThreadLocal（TTL）就是干这个的，关键是——包装一次线程池，全局生效，不要让业务代码自己去 copy。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 把上下文容器换成 TransmittableThreadLocal
public class UserContextHolder {
 private static final TransmittableThreadLocal<UserContext> CTX = new TransmittableThreadLocal<>();
 public static void set(UserContext c) { CTX.set(c); }
 public static UserContext current() { return CTX.get(); }
 public static void clear() { CTX.remove(); }
}

// 包装一次线程池，之后所有 submit 都会自动捎带上下文
ExecutorService pool = TtlExecutors.getTtlExecutorService(originalPool);
pool.submit(() -> {
 String userId = UserContextHolder.current().getUserId(); // 仍然取得到
 // ...
});

跨进程异步：消息队列怎么传？

HTTP 调用有请求头，消息队列也有"信封"——大多数 MQ 都支持消息 Header / Properties。把用户上下文放进去就行：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


// 生产端：发消息时把上下文塞进 Header（以 Kafka 为例）
public void send(String topic, byte[] payload) {
 UserContext ctx = UserContextHolder.current();
 ProducerRecord<String, byte[]> record = new ProducerRecord<>(topic, payload);
 if (ctx != null) {
 record.headers().add("X-User-Id", ctx.getUserId().getBytes(StandardCharsets.UTF_8));
 record.headers().add("X-Tenant-Id", ctx.getTenantId().getBytes(StandardCharsets.UTF_8));
 }
 producer.send(record);
}

// 消费端：消费前恢复上下文
public void onMessage(ConsumerRecord<String, byte[]> record) {
 UserContext ctx = UserContext.builder()
 .userId(header(record, "X-User-Id"))
 .tenantId(header(record, "X-Tenant-Id"))
 .build();

 UserContextHolder.set(ctx);
 try {
 handle(record.value());
 } finally {
 UserContextHolder.clear();
 }
}

同样，这件事应该做在 Producer/Consumer 的拦截器里，对业务代码透明。

一个被忽视的语义陷阱

异步场景里有个微妙的区别：操作发起人 vs 消费执行人。

举个例子：用户 A 下单后，订单服务发了一条消息，积分服务异步消费给 A 加分。

这条消息的"操作发起人"是用户 A——给 A 加分用的就是这个 ID。
但消息消费时，处理这条消息的"执行身份"可能是一个系统账号——发起后续调用（比如调风控）时，下游需要知道的是"系统在调"，不是"A 在调"。

所以在比较复杂的系统里，消息上下文里通常要分清两类字段：

业务用户：X-User-Id，描述"这件事跟谁有关"
执行主体：X-Actor-Id，描述"现在是谁在干"

两者不要混。

进阶视角：Service Mesh 方案

把视角再拔高一层——身份认证、上下文注入这些事，到底应该写在业务进程里，还是放到基础设施里？

Service Mesh（Istio 是典型代表）给了第三种答案：让 Sidecar 来管。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


┌──────────────────┐ ┌──────────────────┐
│ 订单服务 │ │ 库存服务 │
│ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │ Business │ │ │ │ Business │ │
│ └──────▲──────┘ │ │ └──────▲──────┘ │
│ │ │ │ │ │
│ ┌──────┴──────┐ │ mTLS │ ┌──────┴──────┐ │
│ │ Sidecar │ ├───────▶│ │ Sidecar │ │
│ └─────────────┘ │ │ └─────────────┘ │
└──────────────────┘ └──────────────────┘
 ↑ ↑
 验 JWT、注入身份头 校验来源、校验身份

每个服务旁边带一个 Sidecar 代理，所有出入流量都被它劫持。

进入服务前：Sidecar 校验 mTLS 证书、解析 JWT、把身份字段以请求头注入
离开服务时：Sidecar 自动签发 mTLS、附带服务身份

业务进程里彻底不需要任何鉴权代码，连"网关解 Token"那一步都被下沉到了基础设施层。

它的代价也很现实：

每个 Pod 多一个代理进程，有性能与资源开销
调用链路上多一跳，问题排查复杂度陡增
需要团队具备 K8s + Mesh 的运维能力

适用边界大致是：服务数量到了几十上百，团队有专门的基础架构组，且对零信任、跨集群通信、灰度路由这类能力有强需求时，才值得引入。中小规模团队用"网关 + 上下文透传"已经足够好。

横向对比与选型建议

方案	改造成本	安全性	性能	适用阶段
朴素参数	低	极低	高	几乎不推荐
Token 全链路	低	中	中	小型 / 探索期
网关 + 上下文透传	中	高	高	大多数公司主流选择
Service Mesh	高	极高	中低	大规模 / 多语言 / 强基建团队

给一个工程上的建议：

初创/小团队：直接做"网关解 Token + 请求头透传"，把上下文工具类和拦截器封装好，业务代码无感即可。Mesh 不必上。
中型团队：在前者基础上，把内网入口封死（mTLS 或共享密钥），把 MQ 也接入同一套上下文透传，做到"链路里任何一跳都知道当前用户"。
大型/多语言团队：考虑把鉴权与上下文注入下沉到 Service Mesh，业务侧只读上下文，不再写任何鉴权代码。

小结

回到开头那个问题——微服务之间到底应如何传递用户信息？

一句话总结：

用户上下文应当像 traceId 一样，在框架层透明流转。业务代码只问"当前是谁"，不关心"怎么传过来的"。

具体落到一套清单：

不要把用户信息混进业务参数，它应该走专门通道。
鉴权只在网关做一次，下游不重复解析 Token。
下游通过约定的请求头读取用户上下文，前提是内网入口必须封死。
服务内部用上下文容器 + 入口/出口拦截器，实现隐式流转。
异步场景（线程池、MQ）单独处理上下文复制，否则一定会丢。
规模到了，再考虑用 Service Mesh 把这件事彻底下沉。

把这条链条闭环建好，未来无论加多少个服务、加多少种身份字段，业务代码都不用动。这才是"基础设施服务于业务"应有的样子。

Nacos 配置中心与服务发现的实战要点

Thu, 20 Jun 2024 15:30:00 +0800

为什么 Nacos 装起来容易，用对很难

Nacos 是当下国内最流行的"配置中心 + 注册中心"二合一组件——几乎所有用 Spring Cloud Alibaba 的项目都默认上它。

但用过的人会发现一些尴尬的事情：

团队所有项目的配置全堆在一个 namespace 里，环境/项目/团队划分混乱
一个微服务有十几个配置文件，谁也说不清哪个配置覆盖了哪个
修改一个配置后有些实例生效，有些没生效——监听机制写错了
重启 Nacos 后配置没了或者注册的服务全没了——存储模式选错了
灰度发布想"只让一台实例生效新配置"，根本做不到

Nacos 装起来 5 分钟，用对要几个月经验。本文把生产环境的关键决策点讲清楚——namespace 怎么划、配置怎么组织、监听怎么写对、服务发现怎么用稳。

一、Nacos 的核心模型

flowchart TB
 Namespace["Namespace
(环境隔离)"]
 Group["Group
(逻辑分组)"]
 DataId["Data ID
(具体配置)"]

 Namespace --> Group
 Group --> DataId

 DataId -.读取.-> Client[应用实例]
 DataId -.推送变更.-> Client

三层模型：

Namespace：最高层级隔离——通常对应环境（dev/test/prod）
Group：第二层逻辑分组——通常对应项目或微服务
Data ID：最具体的配置文件——application-{profile}.yaml

这个三层结构怎么划分，是 Nacos 用得好不好的最大决定因素。

二、Namespace / Group / DataId 的划分原则

不要这样划

1
2
3
4


namespace: public（默认）
group: DEFAULT_GROUP
data id: my-service-dev.yaml, my-service-test.yaml, my-service-prod.yaml
my-other-service-dev.yaml, ...

所有配置堆在 default 命名空间和 default 组里——搜起来一团乱，多团队协作时互相覆盖也不会知道。

推荐划法：环境隔离 + 服务分组

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


namespace = 环境
 ├─ dev
 ├─ test
 ├─ pre (预发布)
 └─ prod

group = 服务名 / 项目名
 ├─ user-service
 ├─ order-service
 └─ shared-config (跨服务共享)

data id = application-{type}.yaml
 ├─ application-base.yaml (业务基础配置)
 ├─ application-rocketmq.yaml (中间件配置)
 └─ application-feature.yaml (功能开关)

关键决策：

Namespace 用环境——上线管控的核心边界。线上账号只给 prod namespace 权限，dev 不该看到 prod
Group 用服务名——同一个微服务的所有 Data ID 集中在一个 Group 里
Data ID 按职责拆分——业务配置、中间件配置、功能开关分开放，单个文件不会膨胀

跨服务共享配置怎么办

很多配置不是单一服务的——比如所有服务都要连同一个 Redis：

1
2


group = shared-config
data id = application-redis.yaml, application-mq.yaml

每个服务在 bootstrap.yml 里多 import 一份共享配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


spring:
 cloud:
 nacos:
 config:
 server-addr: ${NACOS_ADDR}
 namespace: ${ENV}
 group: user-service  # 自己的 group
 extension-configs:
 - data-id: application-redis.yaml
 group: shared-config
 refresh: true
 - data-id: application-mq.yaml
 group: shared-config
 refresh: true

三、配置文件的优先级和加载顺序

Spring Cloud Nacos 默认按这个优先级加载（从低到高）：

${spring.application.name}.${file-extension} 默认共享
${spring.application.name}-${profile}.${file-extension}（profile 独占）
extension-configs（按数组顺序，越后越高）
shared-configs（按数组顺序，越后越高）
命令行参数 / 环境变量

搞清楚这个优先级是排查"为什么我改了配置不生效"的前提——很可能你改的是低优先级，被高优先级覆盖了。

打开 Spring Boot Actuator 的 /actuator/configprops 或者 /actuator/env 能直观看到每个 key 来自哪个 PropertySource。

四、配置变更的监听：写错就完蛋

默认行为：自动刷新被 `@Value` 注入的字段

1
2
3
4
5


spring:
 cloud:
 nacos:
 config:
 refresh: true

1
2
3
4
5
6


@RestController
@RefreshScope // ★ 关键
public class FeatureController {
 @Value("${feature.enabled}")
 private boolean enabled;
}

@RefreshScope 让 Bean 在配置变更后重新创建，注入的 @Value 拿到新值。

容易踩的坑

坑 1：@RefreshScope 没加，配置不生效

新人最常踩——以为配 refresh: true 就够了。实际上还要在使用配置的 Bean 上加 @RefreshScope。

坑 2：@RefreshScope 不能加在 @Configuration 上

会导致整个 Configuration 重建，下面声明的所有 Bean 全部重建——副作用极大，可能引起内存泄漏（旧 Bean 没释放）。

坑 3：@ConfigurationProperties 默认就刷新

不需要 @RefreshScope：

1
2
3
4
5
6
7


@Component
@ConfigurationProperties(prefix = "feature")
public class FeatureConfig {
 private boolean enabled;
 private int threshold;
 // getters / setters
}

这是更推荐的姿势——比 @Value 类型安全、便于测试、自动刷新。

坑 4：手动监听用 @NacosConfigListener 已废弃

老博客经常推荐 @NacosConfigListener，但它属于早期 SDK 风格，Spring Cloud 集成下基本不该用。手动监听用：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


@Autowired NacosConfigManager configManager;

@PostConstruct
public void listen() throws Exception {
 configManager.getConfigService().addListener(
 "application-feature.yaml", "user-service",
 new Listener() {
 public Executor getExecutor() { return null; }
 public void receiveConfigInfo(String content) {
 log.info("config changed: {}", content);
 // 自定义解析逻辑
 }
 });
}

但 99% 场景用 @ConfigurationProperties + @RefreshScope 就够了。

五、灰度发布：Nacos 自身能做到什么程度

很多人以为"灰度发布配置"是 Nacos 的标准能力——Nacos 开源版其实没有灰度配置。

Nacos 开源版：配置变更会推到所有订阅了这个 Data ID 的实例，没有"只推一台"的能力
Nacos 商业版（阿里云 MSE Nacos）：才有"配置灰度发布"功能，可以指定按 IP / 标签推送

如果用开源版又想做配置灰度，三种思路：

拆 namespace：灰度环境用单独的 namespace（最干净）
拆 group：同 namespace 不同 group，灰度实例订阅 xxx-gray group
配置里写规则：配置内容里写"哪些实例生效"，业务代码读自己 IP 来判断（最灵活但侵入大）

生产推荐方案 1：直接搞一个 pre namespace 给灰度环境，和 prod 完全隔离。

六、服务发现：被低估的复杂度

临时实例 vs 永久实例

Nacos 注册的服务有两种"实例类型"：

临时实例（默认）：客户端用心跳维持，断了 30 秒后自动剔除——适合业务微服务
永久实例：服务端永久持有，下线要主动调 API——适合有固定地址的传统服务（数据库、第三方系统）

1
2
3
4
5


spring:
 cloud:
 nacos:
 discovery:
 ephemeral: true # 临时实例

注意：1.x 时代两者可以混在同一服务，2.x 之后同一 service 必须全是临时或全是永久——升级时要核对。

心跳与剔除

版本差异（重要）：下面"5 秒心跳 / 15 秒不健康 / 30 秒剔除"是 Nacos 1.x（HTTP 短连接） 的行为；Nacos 2.x 起默认改为 gRPC 长连接 + keepalive——客户端不再定时发 HTTP 心跳，连接断开即被识别下线，整体响应时延显著缩短（亚秒级）。如果你用的是 2.x（2024 年起的主流版本），心跳模型已经不适用。

Nacos 1.x 行为：临时实例每 5 秒发心跳，15 秒没心跳变"不健康"，30 秒后剔除——这意味着实例突然 kill 后最长有 30 秒不可用窗口。

Nacos 2.x 行为：客户端与 server 维持 gRPC 长连接，server 通过连接状态判断实例存活；连接异常断开（进程崩溃、网络隔离）会立即触发下线事件，避免 30 秒窗口。

解决（不论版本都建议）：

客户端配置健康检查 + 重试（OpenFeign / Ribbon / Spring Cloud LoadBalancer）
实例下线前先调用 Nacos NamingService.deregisterInstance 优雅注销——通常用 Spring Boot 的 ApplicationListener<ContextClosedEvent>

七、生产部署：踩过的坑

1. 数据存储：默认嵌入式不能上生产

Nacos 单机默认用嵌入式 Derby 数据库——重启数据可能丢，集群模式根本无法工作。生产必须切到 MySQL：

1
2
3
4
5
6
7


# Nacos 1.x / 2.x 老 key（仍兼容）
spring.datasource.platform=mysql
# Nacos 2.2+ 自身基于较新 Spring Boot，server 端推荐改用：spring.sql.init.platform=mysql
db.num=1
db.url.0=jdbc:mysql://nacos-mysql:3306/nacos?characterEncoding=utf8&...
db.user=nacos
db.password=...

2. 集群模式：至少 3 节点

Nacos 是双协议架构——配置中心和永久实例走 JRaft（CP），默认服务发现的临时实例走自研的 Distro（AP）协议 。两类数据落到同一个集群、用不同的一致性模型。至少 3 节点保证高可用——单节点是写测试代码用的，生产部署单节点没有任何高可用保证，强烈不建议。

这个差异在调试时很重要：Distro 是 AP，节点挂掉时部分实例信息可能短暂不一致——这是设计如此，不是 bug。

flowchart LR
 LB[负载均衡 / SLB]
 LB --> N1[Nacos 1]
 LB --> N2[Nacos 2]
 LB --> N3[Nacos 3]
 N1 <--> MySQL[(MySQL 主从)]
 N2 <--> MySQL
 N3 <--> MySQL

3. 安全：默认是裸奔的

Nacos 默认没有鉴权——任何能访问端口的人都能改你的配置。生产必须开启：

1
2
3


nacos.core.auth.enabled=true
nacos.core.auth.server.identity.key=...
nacos.core.auth.server.identity.value=...

并给不同环境账号、不同 namespace 设置不同权限（开源版控制台里能配）。

4. JVM 参数

生产 Nacos 的 JVM 参数默认是 -Xms2g -Xmx2g，对大流量场景明显不够。配置数 ≥ 10000、连接客户端 ≥ 1000 时建议升到 4G 以上。

5. 不要在容器里跑临时数据

K8s 部署 Nacos 时，所有数据必须挂 PV，否则 Pod 重启数据全丢。MySQL 走外部，但 Nacos 自己的 logs / data 目录也要挂。

八、客户端容错：Nacos 挂了应用还能跑吗

Nacos 故障时（虽然概率小），客户端默认还能从本地 snapshot 文件读取上次拉到的配置——不会立刻挂：

1

~/nacos/config/snapshot/{namespace}/{group}/{dataId}

但有几个细节：

新增实例在 Nacos 故障时拉不到任何配置——直接启动失败
服务发现故障时正在运行的实例还能用上次缓存的服务列表，但新启动的实例发现不了任何服务

所以生产环境永远要保证：

Nacos 集群必须多节点 + 跨可用区
应用启动时用本地 fallback 配置（spring.cloud.nacos.config.import-check.enabled=false）
重要服务的服务发现要有降级机制

九、监控与排查

1. 看配置历史

Nacos 控制台保留每次变更的历史，改错了能直接 rollback。这是 Nacos 区别于"配置写在 yaml 里 + git" 模式的核心价值——不需要发版本就能改配置，但同时有审计。

2. 看订阅者

Nacos 控制台 → 配置详情 → “订阅者列表”，能看到当前哪些实例订阅了这个配置——调试"为什么我的应用没收到推送"的第一步。

3. 应用侧日志

1

DEBUG com.alibaba.nacos.client = DEBUG

打开后能看到拉配置、心跳、推送等所有交互的细节。

十、生产配置 Checklist

部署前对照这份清单：

Namespace 按环境划分
Group 按服务划分
Data ID 按职责拆分（业务/中间件/开关）
共享配置走 shared-configs
使用 @ConfigurationProperties 而非 @Value
@RefreshScope 不加在 @Configuration 上
数据存储改 MySQL（不要嵌入式 Derby）
集群模式 ≥ 3 节点
鉴权开启 + 多账号权限隔离
JVM 内存 ≥ 4G
K8s 部署挂 PV
应用启动有 fallback 配置
Actuator 监控接入
业务配置变更走审批流程

小结

把全文压一句：

Nacos 的真正价值不在『配置存哪里』，而在『配置变更能可控、可审计、能秒级生效』——但要让它真正可靠，命名空间、监听机制、集群部署一个都不能省。

记住几条工程纪律：

环境分 namespace，服务分 group，配置按职责拆 Data ID
优先 @ConfigurationProperties，少用 @Value + @RefreshScope
生产必上 MySQL + 3 节点 + 鉴权
永远要有本地 fallback——配置中心是单点故障源

把 Nacos 用对，是国内 Spring Cloud 项目走得远的基础设施之一。

Spring Cloud 微服务之间如何避免循环依赖

Thu, 11 Apr 2024 16:00:00 +0800

一个隐性而致命的问题

微服务团队成长到一定规模后，几乎都会遇到服务之间的循环依赖：

1

订单服务 → 用户服务 → 订单服务

朴素的解决思路：“只是调用关系而已，能跑就行”——但这种循环会带来一系列问题：

启动顺序混乱：A 启动时要连 B 的健康检查，B 启动时要连 A 的——谁先启动？
故障爆炸式扩散：A 挂 → B 挂 → A 挂——单点故障变成集群故障
测试灾难：要起 A 必须先起 B、起 B 必须先起 A
架构腐化：循环让"职责边界"完全消失——任何修改都要全链条考虑
死锁/雪崩风险：链路超时、回调嵌套、连接池耗尽
重构寸步难行：想拆分服务时所有循环都拦着

循环依赖不是技术问题，是架构问题。本文从识别、分析、解决三个层面讲清楚。

一、循环依赖的几种典型形态

1. 直接循环（A ↔ B）

flowchart LR
 A[订单服务] -->|查用户信息| B[用户服务]
 B -->|查用户最近订单| A

最常见的——双方都要对方的数据。

2. 间接循环（A → B → C → A）

flowchart LR
 A[订单服务] --> B[支付服务]
 B --> C[风控服务]
 C --> A

链路一长就难发现——往往是新增功能时引入的。

3. 通过事件的"软循环"

flowchart LR
 A[订单] -->|OrderCreated 事件| MQ
 MQ --> B[积分服务]
 B -->|RPC 查订单状态| A

虽然是异步，但积分服务回头查订单服务——本质上还是循环。

4. 启动期循环

A 启动时要从 B 拉某个全局配置，B 启动时也要从 A 拉某个配置——启动期死锁。

二、为什么循环依赖会出现

业务视角看是"一不小心引入"——但本质原因通常是：

1. 实体边界没分清

订单和用户都是核心实体——从用户视角"查我的订单"、从订单视角"查谁下的单"——两个视角看起来都合理，于是双向都建了 RPC。

2. 共享数据没有归属

“用户最近一笔订单”——这个数据算用户属性还是订单属性？没人 say 清楚归谁，最后就两边都查。

3. 微服务过细

把"用户登录"和"用户资料"拆成两个服务——结果它们成天互相调用。过度拆分是循环的温床。

4. 业务驱动反向调用

最常见的——“产品要订单详情页面也展示用户头像”：

1

订单服务（主）→ 用户服务 ✓ 正常依赖

下一个版本，“用户主页要展示最近订单”：

1

用户服务（主）→ 订单服务 ❌ 反向依赖来了

业务一推动就改，没人检查依赖图——循环就此诞生。

三、识别：怎么发现循环

1. 静态扫描

整理所有服务间的 OpenFeign / RestTemplate 调用：

1

grep -r "@FeignClient" --include="*.java"

输出每个服务依赖哪些服务，画个有向图——用 Graphviz 或简单的脚本。

2. 链路追踪

SkyWalking / Zipkin / Jaeger 在生产里聚合调用拓扑——自动看到 A 调 B、B 调 A。

3. 服务注册中心

Nacos / Consul 看每个服务的调用方列表——能看到反向依赖。

4. 在 CI 加检查

1
2
3


# 每次 PR 检查依赖图，新增反向调用直接 fail
- name: Check service dependencies
 run: ./scripts/check-deps.sh

把检查变成机制——比每次 review 时人工排查靠谱。

四、解决方案

方案 1：合并服务（最直接）

如果 A 和 B 长期互相调用——它们可能就该是一个服务。微服务不是越细越好——业务边界不清的两个服务合并回去是合理的。

判断标准：

数据强一致需求
改动通常一起来
链路上 80% 都是双向调用

方案 2：抽出共享层

A 和 B 都依赖某段共享逻辑/数据——抽到 C：

1
2


重构前：A ↔ B
重构后：A → C ← B

例如"用户基础信息"抽到 user-base 服务——A 和 B 都查 C，互不依赖。

方案 3：事件驱动 + 数据冗余

最优雅但工程量大——A 改了数据后发事件，B 订阅事件维护自己一份冗余：

flowchart LR
 A -->|UserUpdated 事件| MQ
 MQ --> B[B 维护用户冗余表]
 User --> B
 B -.无需调 A.-> B

B 不再实时调 A 取数据——读自己的本地冗余。代价是数据有微小延迟，但循环彻底消除。

方案 4：依赖反转

A 调 B 是为了"通知 B 一件事"——改成 B 主动监听：

1
2


重构前：A → B（通知 B 用户状态变化）
重构后：A 发事件 → B 订阅

依赖方向倒过来——A 不再依赖 B。

方案 5：API Gateway / BFF 聚合

页面需要 A + B 的数据——不应该让 B 调 A，应该让 BFF（Backend For Frontend）调 A 和 B 聚合：

flowchart LR
 Frontend --> BFF
 BFF --> A
 BFF --> B

A 和 B 的依赖被 BFF 拆开——它们之间不再相互依赖。

方案 6：批量查询代替单次

如果 B 调 A 是为了"批量查 1000 个用户的订单"——让 A 提供批量接口，B 拿到 ID 列表后批量请求一次：

1
2


之前：B 循环 1000 次调 A
之后：B 一次性发 1000 个 ID 给 A

调用次数大幅降低 → 即使保留依赖，影响也小。

五、典型场景的具体解法

场景 1：订单展示要用户头像，用户主页要展示订单数

重构前	重构后
订单服务 ↔ 用户服务（互相调用）	BFF 聚合：BFF → 订单服务、BFF → 用户服务
	订单服务里冗余存 user_name + avatar_url

场景 2：积分服务通过事件加积分，但要查订单金额

重构前	重构后
订单 → 发事件 → 积分 → RPC 查订单	订单发事件时事件载荷里就带金额

场景 3：风控决策要查多个上下文

重构前	重构后
风控服务 ↔ 订单 ↔ 用户 ↔ 风控	调用方主动把上下文打包传给风控

六、架构层面的纪律

1. 严格的"上下游"层级

把服务分层——只允许上层调下层，下层永不调上层：

flowchart TD
 BFF[BFF / API 层]
 BFF --> Domain[业务领域服务]
 Domain --> Foundation[基础服务
用户/账户/支付]
 Foundation --> Infra[基础设施
消息/存储/索引]

任何"下层调上层"PR 直接 reject。

2. 共享数据归属唯一

每个数据的"主人"只有一个服务——其他服务要用，要么调主人，要么订阅事件维护冗余。

3. 增量加 PR 时强制依赖检查

1
2
3


# 检查是否引入新的 cross-tier 依赖
- name: Check architecture
 run: archunit-test

ArchUnit 这种工具能在测试里强制架构规则——机制保证大于人为约束。

4. 定期审视依赖图

每个迭代结束 review 一次依赖图——发现"上次没有的反向依赖"立刻处理。

七、Spring Cloud 特有的注意点

1. OpenFeign 自调本服务的隐患

服务内部代码注入指向"本服务名"的 FeignClient：

1
2
3
4
5
6
7
8


@FeignClient(name = "user-service")
public interface UserClient { ... }

// 用户服务里
@Service
class UserService {
 @Autowired private UserClient userClient; // 指向本服务
}

这种用法不会立刻报错——Feign 通过注册中心负载均衡转发，请求会落到本服务的某个实例（可能是自己也可能是同名其他实例）。但它是个反模式：

普通自调虽不立刻失败，但会绕一跳网络、多一段 trace、丢失本地事务上下文
若调用链最终回到调用方所在的同一个接口（A 通过 LB 调到 A 自己，又走相同方法），就会形成无限递归 → 栈溢出 / 连接池耗尽
调用链路在 trace 里突然多一段，排查困难

结论：本服务的内部能力直接走 Bean 调用，不要通过 FeignClient 绕一圈。要复用接口契约可以把 Client 接口和 Controller 实现拆出 SPI 模块共享。

2. Eureka / Nacos 服务发现的循环

A 启动时连不上 B，B 启动时连不上 A——注册中心会等到双方都活着才允许调用。但如果配置了"启动期健康检查"，就会双方互等。

解决：启动期检查只用基础设施（DB、Redis），不要互相检查。

3. 配置中心的循环

A 服务启动时要从配置中心拉 B 的地址——但配置中心要先注册到 A 才能正常工作？这种设计是错的。配置中心应该是最底层无依赖的服务。

八、一份"循环依赖"治理清单

发现循环后按这个流程处理：

明确循环类型——直接 / 间接 / 软 / 启动期
画出当前依赖图
判断业务边界——是不是该合并服务？
如果不合并——选方案：抽共享层 / 事件 + 冗余 / 依赖反转 / BFF
设计冗余数据的同步机制——保证最终一致
测试覆盖——确保循环消除后业务不退化
加 ArchUnit 检查防止回退

九、一些反例

反例 1：为了"性能"双向冗余

A 存 B 的数据、B 存 A 的数据——两边都要同步对方的变化。最终变成"两个真相"——数据不一致。冗余应该单向。

反例 2：用 MQ 假装解耦

1
2


A → MQ → B
B → MQ → A

虽然走 MQ 不直接调用，但本质还是循环——只是把同步等待换成异步等待。问题没解决。

反例 3：用注释"承认循环"

1
2


// TODO: 这里是循环依赖，暂时无法避免
@Autowired private UserClient userClient;

写注释承认问题等于不解决——技术债越堆越多。循环依赖应作为架构债务专项跟踪，原则上不允许长期存在。

小结

把全文压一句：

服务间循环依赖不是『可以容忍的小毛病』——它是架构腐化的早期信号，会慢慢腐蚀整个系统。发现一个解决一个。

工程纪律：

服务分层，禁止上下层逆向调
数据归属唯一，跨域用事件 + 冗余
共享逻辑下沉到独立服务
页面聚合走 BFF
CI 自动检查，不靠人工
循环依赖出现立刻处理，不容忍

把这套做对，微服务才能真正"独立、可演进、可扩展"——而不是变成"分布式单体"。

Spring Reactor 入门与常见陷阱

Fri, 24 Nov 2023 16:00:00 +0800

写在前面

Spring 5 引入 WebFlux 后，“响应式编程"成了 Java 圈无法绕过的话题。但多数人对 Reactor 的理解止于：

“把 List 换成 Flux 不就行了？把 Object 换成 Mono？”

实际写起来你会发现根本不是这回事——

同步代码改成 Reactor 后性能不一定提升
一不小心 .block() 一下，所有响应式优势瞬间归零
异常处理逻辑要重新设计
ThreadLocal、Spring Security context 全部不见了

Reactor 不是『async 的语法糖』——它是另一种编程范式。本文用最少的概念把 Reactor 讲清楚：核心思想、Mono / Flux、操作符、调度器、和典型陷阱。

一、为什么需要响应式

传统 Spring MVC 的线程模型是一请求一线程：

flowchart LR
 R1[Request 1] --> T1[Thread 1
占用整个生命周期]
 R2[Request 2] --> T2[Thread 2]
 R3[Request 3] --> T3[Thread 3]
 T1 --> DB1[(DB query 100ms)]
 T2 --> DB2[(DB query 200ms)]

Tomcat 默认线程池 200 个——理论上 200 并发。但实际上每个线程在等数据库时完全空闲——CPU 浪费、内存占用大。

响应式的思路是 少线程 + 异步驱动：

flowchart LR
 R1[Request 1] --> EL[Event Loop
单/少线程]
 R2[Request 2] --> EL
 R3[Request 3] --> EL
 EL -.异步.-> DB[(DB)]
 DB -.callback.-> EL

请求来了立刻挂起 callback，不占线程；DB 返回时再继续——几个线程能撑几万 QPS。

这就是 Node.js / Netty / Reactor 的哲学。

二、Reactor 的两个核心类型

Mono：0 或 1 个值的异步流

1

Mono<User> user = userRepo.findById(1L);

类似 Optional<CompletableFuture<T>>——可能有值、可能没值、可能异步。

Flux：0 到 N 个值的异步流

1

Flux<User> users = userRepo.findAll();

类似 Stream<CompletableFuture<T>>——一系列异步到达的元素。

共同特征：lazy

1
2
3
4


Flux<Integer> f = Flux.range(1, 10).map(i -> i * 2);
// 此时什么都没发生
f.subscribe(System.out::println);
// 现在才执行

没有 subscribe 就什么都不会发生——这是初学者最大的坑（“为什么我的 log 没打印”）。

三、常用操作符

创建

1
2
3
4
5
6
7
8
9


Mono.just(value) // 单个值
Mono.empty() // 空
Mono.error(new RuntimeException())
Mono.fromCallable(() -> ...) // 包装阻塞调用

Flux.just(1, 2, 3)
Flux.range(1, 100)
Flux.fromIterable(list)
Flux.interval(Duration.ofSeconds(1)) // 每秒发一个

转换

1
2
3
4


Flux.range(1, 5)
 .map(i -> i * 2) // 同步转换
 .flatMap(i -> Mono.fromCallable(() -> rpcCall(i))) // 异步转换
 .filter(i -> i > 5)

map vs flatMap 的差异：

map：T → R
flatMap：T → Mono / Flux，会"展平"嵌套

组合

1
2
3
4
5


Mono.zip(getUserA(), getUserB()) // 并行执行，全部完成后合并
 .map(t -> new Pair(t.getT1(), t.getT2()));

Flux.merge(streamA, streamB) // 多流交错合并
Flux.concat(streamA, streamB) // A 完后再 B

错误处理

1
2
3
4


mono.onErrorReturn(defaultValue) // 出错给默认值
 .onErrorResume(e -> backupMono) // 出错切到备用流
 .retry(3) // 重试
 .timeout(Duration.ofSeconds(5)); // 超时

终止

1
2


mono.subscribe(value -> ..., err -> ..., () -> done); // 触发执行
mono.block(); // ⚠️ 阻塞拿值

四、调度器：在哪个线程执行

Reactor 的关键之一——控制每段代码跑在哪个线程：

1
2
3
4
5


Mono.fromCallable(() -> jdbcQuery()) // 阻塞调用
 .subscribeOn(Schedulers.boundedElastic()) // 移到 IO 线程池
 .map(this::transform) // 仍在 IO 线程
 .publishOn(Schedulers.parallel()) // 切到 CPU 线程池
 .map(this::heavyCompute); // 在 CPU 线程

主流调度器：

调度器	用途
`Schedulers.parallel()`	CPU 密集，线程数 = 核数
`Schedulers.boundedElastic()`	阻塞 IO（默认线程上限 10×CPU，每线程任务队列上限 100k，空闲 60s 自动回收）
`Schedulers.single()`	全局共享单线程
`Schedulers.immediate()`	当前线程直接执行

subscribeOn vs publishOn

	subscribeOn	publishOn
影响范围	整条链（从源开始）	之后的操作符
多次调用	只有第一次生效	每次都生效，切换线程
典型用途	把"源头"放到对应线程	中途切换线程

记住：subscribeOn 全局生效一次，publishOn 每次都生效。

五、阻塞与响应式的边界

Reactor 的最大原则——响应式链里绝不能有阻塞代码。

1
2
3
4


// ❌ 反例
Mono.just(id)
 .map(i -> jdbcTemplate.queryForObject("SELECT ...", ...)) // 阻塞！
 .subscribe();

JDBC 是阻塞的——直接放在 map 里会阻塞 Reactor 的事件线程，整个应用响应能力归零。

正确做法 1：包到 fromCallable + boundedElastic：

1
2
3


Mono.fromCallable(() -> jdbcTemplate.queryForObject("SELECT ...", ...))
 .subscribeOn(Schedulers.boundedElastic()) // 在 IO 池跑
 .map(this::transform);

正确做法 2：用响应式驱动（R2DBC 替代 JDBC）：

1
2


DatabaseClient client = ...;
client.sql("SELECT ...").map(row -> ...).first(); // 原生响应式

R2DBC、Spring Data Reactive Mongo / Redis、WebClient 都是响应式驱动——整条链是真异步。

六、几个最常被踩的坑

1
2
3
4


public void process() {
 fluxOfWork.map(...).subscribe(...); // 启动了
 monoOfThing.map(...); // ❌ 没 subscribe，这条链永远不跑
}

Reactor 链一旦写出来就要 subscribe，否则等于死代码。

2. block() 滥用

1

User user = userRepo.findById(id).block(); // 把异步变同步

.block() 让响应式优势全没了——主要用在测试代码、main 函数、或与同步框架/启动初始化的桥接处。生产代码里大面积出现 .block() 通常是反模式信号。

3. ThreadLocal 失效

1
2
3


Mono.fromCallable(() -> {
 // ThreadLocal 拿不到——线程切换了
})

线程跨切换后 ThreadLocal、Spring Security 上下文都丢失。Reactor 提供 Context 替代：

1
2
3
4


Mono.deferContextual(ctx -> {
 String userId = ctx.get("userId");
 return service.process(userId);
}).contextWrite(Context.of("userId", currentUserId));

4. 顺序保证

1
2
3


Flux.range(1, 100)
 .flatMap(i -> remoteCall(i)) // 并发执行，结果顺序乱
 .subscribe(System.out::println);

flatMap 默认并发——结果顺序不保证。要保序用 concatMap：

1

.concatMap(i -> remoteCall(i)) // 串行执行，保序

5. Hot vs Cold

1
2
3
4
5
6
7
8


Flux<Integer> cold = Flux.range(1, 5);
cold.subscribe(System.out::println); // 1 2 3 4 5
cold.subscribe(System.out::println); // 1 2 3 4 5（每个 subscriber 都从头）

Flux<Long> hot = Flux.interval(Duration.ofSeconds(1)).share();
hot.subscribe(System.out::println); // 0 1 2 ...
Thread.sleep(3000);
hot.subscribe(System.out::println); // 3 4 5 ...（错过的丢了）

Cold 流给每个 subscriber 重放；Hot 流是广播——搞错会导致数据丢失。

七、WebFlux：响应式 Web

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@RestController
public class UserController {

 private final UserRepository repo;

 @GetMapping("/users/{id}")
 public Mono<User> getUser(@PathVariable Long id) {
 return repo.findById(id);
 }

 @GetMapping("/users")
 public Flux<User> listUsers() {
 return repo.findAll();
 }

 @PostMapping("/users")
 public Mono<User> create(@RequestBody Mono<UserDTO> dto) {
 return dto.map(this::toEntity).flatMap(repo::save);
 }
}

WebFlux 用 Netty 做底层，单服务器能撑数万长连接——比 MVC 模型在高并发场景下省资源。

但WebFlux 不是『性能银弹』——

业务复杂、JDBC 重的场景，MVC 反而更简单
团队没有响应式经验时，WebFlux 的代码维护成本高
99% 的中小项目用 MVC 完全够

八、调试响应式代码

log() 操作符

1
2
3
4


mono.log("user-fetch")
 .map(...)
 .log("after-map")
 .subscribe();

打印每一步的 onSubscribe、request、onNext、onComplete、onError——是调试响应式链最基础的方法。

checkpoint

1
2
3
4
5


Flux.range(1, 5)
 .checkpoint("after-range")
 .map(i -> 100 / (i - 3))
 .checkpoint("after-divide")
 .subscribe(...);

checkpoint 给错误堆栈加标签——出错时能立刻定位到哪一段。

Reactor Tools

启动时 Hooks.onOperatorDebug() 让所有错误带完整堆栈——性能影响大，仅开发调试用。

九、什么场景值得用 WebFlux

✅ 适合：

大量 IO 等待（如 fetch 多个 RPC 然后聚合）
长连接（SSE / WebSocket / 流式响应）
网关/代理类应用（高并发转发）
集成响应式数据源（R2DBC + WebClient + Reactive Redis）

❌ 不适合：

CPU 密集业务——线程模型变化无收益
JDBC + JPA 重度依赖——R2DBC 生态远不如 JPA 成熟
小团队、传统业务——MVC 简单就行

小结

把全文压一句：

Reactor 不是『async 包装』，是『让你以"数据流"思维重写程序』——核心收益在 IO 密集、高并发场景，但要付出整条链路全异步的代价。

工程要点：

没 subscribe 不会执行
.block() 是反模式
阻塞代码必须用 boundedElastic
ThreadLocal 失效，用 Context
flatMap 不保序，concatMap 保序

掌握 Reactor 不只是学几个 API——是接受"程序由数据流驱动"这种思维。值得每个 Spring 开发者了解，但不必每个项目都用。

聊聊营销平台中常见的指标：PV、UV、转化、留存、ROI

Tue, 15 Aug 2023 16:00:00 +0800

数据指标是营销平台的语言

营销平台里所有讨论都围绕几个核心指标——PV、UV、UA、转化率、留存率、ROI、CPA、CPC、CPM、LTV……

新人面对这些缩写常常一脸懵。等到要做：

“为什么这周 UV 降了 20%？”
“这次活动 ROI 是多少？怎么算的？”
“你说留存率不对——具体哪里不对？”

光知道概念是不够的。指标背后的口径、陷阱、计算方式才是关键。本文把营销平台最常见的指标讲清楚，带工程视角看怎么实现、怎么避免常见坑。

一、流量类指标：PV / UV / UA

PV（Page View）

页面浏览量——用户每打开一次页面就 +1。

1
2
3


SELECT count(*) AS pv
FROM event
WHERE event_name = 'page_view' AND date = '2023-08-15';

特点：

同一用户刷新一次页面 +1
不同用户访问同一页面，各 +1

UV（Unique Visitor）

独立访客数——每个用户当天只算一次。

1
2
3


SELECT count(DISTINCT user_id) AS uv
FROM event
WHERE event_name = 'page_view' AND date = '2023-08-15';

PV / UV 的比值叫"人均 PV"——反映用户活跃程度。

UA（Unique Action）

独立动作数——比 UV 更细粒度，按某个具体动作算去重。比如"独立点击数"、“独立购买用户”。

三个指标的关系

1

PV ≥ UA ≥ UV

PV 包含所有访问，UA 是某个动作的去重，UV 是用户去重。

第一个常见陷阱：UV 怎么定义"用户"

未登录用户怎么算 UV？——通常用 device_id / cookie_id / client_id。但：

同一用户用三个设备访问 → 算 3 个 UV？
同一设备多个浏览器 → 算 N 个 UV？
用户清缓存后 → 又是新 UV？

不同公司有不同口径。最重要的是『团队对口径达成一致』——别在数据评审会上才发现你和数据组算法不一样。

二、漏斗指标：转化率

单步转化率

1

某一步动作人数 / 上一步动作人数 = 单步转化率

例：

100 人看到广告（曝光）
30 人点击了广告（点击率 = 30%）
5 人完成下单（购买率 = 5/30 ≈ 16.7%）
整体转化（曝光到购买） = 5/100 = 5%

漏斗分析

flowchart LR
 A[曝光 100] --> B[点击 30]
 B --> C[加购 12]
 C --> D[下单 5]
 D --> E[支付 4]

每一步流失多少——找到漏斗最大流失点对应的优化机会。

漏斗的"窗口"问题

转化是有时间窗口的。“看了广告 N 天内购买"算转化吗？

同会话内（30 分钟）→ 直接转化
当日内 → 当日转化
7 天内 → 7 天归因转化
30 天内 → 30 天归因转化

不同窗口对应的数字差几倍。看转化率必须搞清楚窗口。

三、留存指标

留存率定义

1

某天的某天 N 留存 = 当日新增用户中，N 天后仍活跃的用户数 / 当日新增用户数

例：8/1 新增 1000 人。8/8 这 1000 人中有 200 人当天活跃 → 8/1 的 7 日留存率是 20%。

次日 / 7日 / 30日留存

行业惯例：

次日留存：用户来了第二天还来——通常 30%-50% 算不错
7 日留存：第 7 天还来——15%-30% 算不错
30 日留存：1 个月后还来——10%-20% 是好产品

留存表（Cohort 分析）

	Day 0	Day 1	Day 7	Day 30
8/1 新增 1000	100%	45%	18%	8%
8/8 新增 1200	100%	50%	22%	10%

按 cohort 看留存——比平均留存信息量大得多。可以看出"哪批用户质量好”、“产品改了之后留存有没有提升”。

实现要点

1
2
3
4
5


-- 8/1 用户 7 日留存
SELECT count(DISTINCT u.user_id) FROM users u
JOIN events e ON e.user_id = u.user_id
WHERE u.register_date = '2023-08-01'
 AND e.event_date = '2023-08-08';

注意 join 大表的性能——生产里通常用 Bitmap / HLL 做近似计算。

四、成本类指标

CPM（Cost Per Mille）

每千次曝光成本：

1

CPM = 总花费 / (曝光数 / 1000)

例：花 1000 元买了 50 万次曝光 → CPM = 1000 / 500 = 2 元。

适合品牌广告——目标是触达，不是直接转化。

CPC（Cost Per Click）

每次点击成本：

1

CPC = 总花费 / 点击数

适合点击付费广告——效果更直接。

CPA（Cost Per Action）

每次目标动作成本——比 CPC 更精细，按"注册"、“下单”、“加好友"等具体动作付费：

1

CPA = 总花费 / 目标动作完成数

	CPM	CPC	CPA
含义	千次曝光	单次点击	单次目标动作
适合	品牌触达	点击行为价值	实际转化收益
风险	平台高	投放方高	投放方高（依赖效果）

五、收益类指标

LTV（Life Time Value）

用户生命周期价值——一个用户从注册到流失，给平台贡献多少收入。

1

LTV = 平均订单金额 × 平均购买频次 × 用户存活时间

例：用户平均下单 100 元、年均下单 5 次、平均留 3 年 → LTV ≈ 1500 元。

LTV 是营销最重要的"上限”——获客成本（CAC）必须 < LTV，否则赔本买卖。

ROI / ROAS

投资回报率 / 广告支出回报：

1
2


ROI = (收入 - 成本) / 成本
ROAS = 广告带来的收入 / 广告花费

业内常说"ROAS 1.5"意味着花 1 元广告费换 1.5 元收入——通常 ROAS ≥ 3 才算健康。

CAC（Customer Acquisition Cost）

获客成本：

1

CAC = 总营销花费 / 新增付费用户数

健康的业务：LTV / CAC ≥ 3——付费用户带来的总收益至少是获客成本的 3 倍。

六、归因模型：转化算谁的

某用户在 30 天里：

8/1 通过广告 A 知道了产品
8/15 通过 SEO 搜索访问了产品
8/29 通过广告 B 点击后下单

这一笔下单算哪个渠道？

模型	算法
First-Touch	全归功于广告 A（首次接触）
Last-Touch	全归功于广告 B（最后接触）—— 最常用
Linear	三者各 1/3
Time-Decay	越靠近转化的权重越大
Position-Based	首末各 40%，中间均分 20%
Data-Driven	机器学习算每个 touchpoint 的实际贡献

不同公司选不同模型——但必须明确告诉所有相关方"我们用什么模型"。否则看到的数字会差几倍。

七、营销实验：A/B 测试

新功能/新页面要不要上线？跑 A/B：

flowchart LR
 Users --> Split["流量分流
50/50"]
 Split --> A[实验组
新版本]
 Split --> B[对照组
旧版本]
 A --> M1[转化率 X%]
 B --> M2[转化率 Y%]
 M1 --> Stat[统计显著性检验]
 M2 --> Stat

关键点

样本量：太少看不出差异——通常要数千以上
置信度：通常 95%——意味着 5% 的概率结果是偶然
实验时长：覆盖完整业务周期（一个工作周 + 一个周末至少）
不要早停：实验跑到一半看到"实验组好"就停掉——选择性偏差

工程实现

1
2
3
4
5
6


public boolean isInExperimentGroup(String userId, String expName) {
 // 用 hash 保证同一用户始终落入同一组
 // ⚠️ Math.abs(Integer.MIN_VALUE) 仍然返回负数，会让 % 出负值，必须先与 0x7FFFFFFF
 int hash = (userId + expName).hashCode() & 0x7FFFFFFF;
 return hash % 100 < 50; // 50% 分流
}

不要随机分流——要确定性 hash，避免同一用户在实验间被反复切换。生产推荐用 Guava Hashing.murmur3_32() 等分布更均匀的 hash 替代 String.hashCode()。

八、典型陷阱清单

1. 指标聚合时的 Simpson 悖论

整体看：A 渠道转化率 5%，B 渠道转化率 4%——A 更好。分群看：男性 A 是 3%，B 是 6%；女性 A 是 8%，B 是 10%——其实都是 B 更好！

别只看整体均值，要分群看。

2. 数据延迟

同一指标，“实时大盘” vs “T+1 报表"可能差 10%——实时数据有未结算、未对账。给老板汇报永远用结算后的数据。

3. 异常流量

突然 PV 暴涨 → 不一定是真实增长，可能是爬虫、脚本、刷量。任何指标异常都要先看流量来源、IP 分布、设备分布。

4. 跨平台 ID 拉通

用户在 PC、H5、App、小程序留下不同 ID——要统一到同一个用户主键才能算准 UV / LTV。这是营销平台的基础工程。

5. 计算口径漂移

“上周 UV 100 万"和"这周 UV 80 万”——也许是统计口径变了，不是真的下降。每次指标讨论先确认口径。

九、技术架构：怎么算这些指标

flowchart TD
 Client[客户端 SDK] --> Collect[埋点采集]
 Collect --> Kafka
 Kafka --> Stream[Flink 实时计算]
 Kafka --> Batch[Spark T+1 计算]
 Stream --> Realtime[(实时指标 Redis)]
 Batch --> Warehouse[(数仓 Hive/ClickHouse)]
 Realtime --> Dashboard[实时大盘]
 Warehouse --> Dashboard
 Warehouse --> BI[BI 报表]

实时指标（PV、UV）：Flink + Redis HLL
离线指标（次留、LTV）：Hive / ClickHouse 批处理
去重：HyperLogLog（HLL）做近似 UV，误差 1-2% 但内存占用极小
漏斗：通常是离线计算

十、给工程的几条建议

指标定义要写文档——口径明确、覆盖所有边界
指标计算代码 + SQL 上版本管理——和业务代码一样审 PR
异常告警要有——指标突然涨/跌 30% 必须触发
跨业务的核心指标统一在一个数据服务——别每个业务方自己实现一套
永远做"指标对账”——多个口径的数字定期 cross-check

小结

把全文压一句：

营销平台的所有讨论都围绕指标——但指标的『口径、归因、时间窗口』比『定义』更关键。算错口径会让团队在错误数据上做错决策。

记住几条：

PV、UV 必须先达成口径共识
转化、留存必须明确时间窗口
CAC、LTV、ROI 决定业务能不能持续
归因模型选哪个，团队要统一
A/B 测试要先算样本量，不要早停

把指标这件事做对，营销平台的"决策质量"会瞬间提一个量级——这是数据驱动的真正价值。

怎么设计一个生产级的验证码系统

Thu, 08 Dec 2022 17:00:00 +0800

谁都遇到过的工具，但很少人做对

短信验证码这事看似简单——“生成 6 位数字、发短信、校验”，但只要你接过线上系统，就一定遇到过这些事故：

凌晨突然被短信轰炸刷了几万条短信，扣费上万
某个手机号被竞争对手循环请求，正常用户收不到
攻击者拿到泄漏的手机号字典，爆破登录接口
客服收到投诉：“我点了 5 次还没收到验证码”——其实是发出去了，被运营商拦了

验证码的设计要同时平衡安全、成本、用户体验三个维度，任何一个出问题都会被现实毒打。本文把一个生产级验证码系统应该考虑的事情过一遍。

一、需求拆解

一个验证码功能，至少要回答这些问题：

问题	决策点
验证码长度?	6 位数字（短信） / 6 位字母数字（邮箱）
有效期?	5 分钟（业内默认）
同一手机号 1 分钟内能再请求吗?	否
同一手机号 1 天最多发几次?	5-10 次
同一 IP 1 小时最多发几次?	20 次（防扫号）
校验失败几次后锁定?	5 次
用过/锁定后能复用吗?	否，立即作废
短信和邮箱分开计数吗?	通常分开

这些数字没有标准答案，根据业务的安全 vs 体验权衡来定。后面所有实现都基于这些规则。

二、整体架构

flowchart LR
 User([用户]) --> API[发送接口]
 API --> Limit{多维限流}
 Limit -->|拒绝| Reject([429])
 Limit -->|通过| Gen[生成验证码]
 Gen --> Store[(Redis
code 存储)]
 Gen --> SMS[短信通道]
 SMS --> Provider[阿里云/腾讯云]
 Provider --> Phone([用户手机])

 User --> Verify[校验接口]
 Verify --> Check{比对 Redis}
 Check --> Result([成功/失败])

核心组件：

验证码生成：随机数字串 + 时间戳
存储：Redis（带 TTL）
限流：Redis 计数器 + Lua 脚本
发送：解耦短信通道
校验：原子读取 + 删除

三、生成与存储

1. 生成

短信验证码不要用 Math.random()，用 SecureRandom：

1
2
3
4
5
6


private static final SecureRandom RANDOM = new SecureRandom();

public String generate() {
 int code = RANDOM.nextInt(900000) + 100000; // 100000-999999
 return String.valueOf(code);
}

Math.random() 是伪随机，对一般业务够用，但对验证码这种安全相关的事，能用 SecureRandom 就用 SecureRandom。

2. 存储

Redis 是最自然的选择——key 带场景标识，value 存"验证码 + 校验失败计数"，TTL 5 分钟：

1

SET sms:login:13800138000 "{\"code\":\"123456\",\"failCount\":0,\"sentAt\":\"...\"}" EX 300

不要用纯字符串 code——校验失败次数、剩余次数都要记下来。

3. 关键：场景隔离

同一手机号在不同业务场景下的验证码必须分开存：

1
2
3


sms:login:13800138000 → 登录用
sms:register:13800138000 → 注册用
sms:reset-pwd:13800138000 → 找回密码用

如果不分场景，攻击者从注册接口拿到验证码，能用来登录别的场景——这是真实发生过的越权事故。

四、多维限流：核心防刷

只做"1 分钟限发一次"是远远不够的。生产系统至少要做四层限流：

1. 同手机号 + 同场景：60 秒间隔

最朴素的——前端按钮置灰是一道，后端必须自己再校验一次：

1
2
3
4
5


String key = "sms:cooldown:login:" + phone;
Boolean ok = redis.opsForValue().setIfAbsent(key, "1", 60, TimeUnit.SECONDS);
if (!ok) {
 throw new BusinessException("请求过于频繁");
}

2. 同手机号每天总量上限

24 小时内最多 10 条，超过拒绝：

1
2
3
4
5
6
7
8


String key = "sms:daily:" + phone;
Long count = redis.opsForValue().increment(key);
if (count == 1) {
 redis.expire(key, 24, TimeUnit.HOURS);
}
if (count > 10) {
 throw new BusinessException("今日发送已达上限");
}

3. 同 IP 限流

防扫号的关键——攻击者写脚本遍历手机号字典：

1
2
3
4
5
6
7
8
9


String key = "sms:ip:" + ip;
Long count = redis.opsForValue().increment(key);
if (count == 1) {
 redis.expire(key, 1, TimeUnit.HOURS);
}
if (count > 20) {
 log.warn("suspicious IP: {}", ip);
 throw new BusinessException("请求过于频繁");
}

4. 全局熔断：每分钟总短信量

防 DDoS 时的最后一道——配置中心维护一个全局阈值：

1
2
3
4
5
6
7


String key = "sms:global:" + minute;
Long count = redis.opsForValue().increment(key);
if (count > globalLimitPerMinute) {
 log.error("SMS global rate limit breached");
 alarm();
 throw new BusinessException("服务繁忙");
}

短信成本可不便宜——这层不开，攻击场景下损失会被迅速放大。

五、发送：人机校验前置

仅靠 IP 限流防不住僵尸网络（每个肉鸡 IP 不同）。真正的最强防御是滑块/拼图/reCAPTCHA——人机校验通过后才允许调发送接口。

flowchart LR
 Front([前端]) --> Slider[滑块校验]
 Slider --> Token[人机校验 Token]
 Token --> API[发送接口]
 API --> Verify{校验 Token}
 Verify -->|无效| Reject
 Verify -->|有效| Send[发送]

后端校验 Token 时要有"一次性"语义——同一个 Token 不能复用。

很多业务做"分层防御"：

第 1 次发送：免人机校验
1 小时内第 2 次：要滑块
第 3 次：要图形+滑块
触发风控：直接拒绝

体验和安全的折中点。

六、校验：原子操作 + 失败次数

校验逻辑看起来简单，但有几个容易写错的细节：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


public boolean verify(String phone, String inputCode, String scene) {
 String key = "sms:" + scene + ":" + phone;
 String json = redis.opsForValue().get(key);
 if (json == null) {
 throw new BusinessException("验证码已过期");
 }
 SmsRecord record = JSON.parseObject(json, SmsRecord.class);

 if (record.getFailCount() >= 5) {
 redis.delete(key); // 锁定
 throw new BusinessException("校验失败次数过多");
 }

 if (!Objects.equals(record.getCode(), inputCode)) {
 record.setFailCount(record.getFailCount() + 1);
 Long ttl = redis.getExpire(key);
 // ⚠️ getExpire 在 key 不存在时返回 -2、无 TTL 时返回 -1
 // 直接当 TTL 用会把 key 写成 "立即过期" 或 "永不过期"——这里要兜底
 if (ttl == null || ttl <= 0) ttl = 300L;
 redis.opsForValue().set(key, JSON.toJSONString(record), ttl, TimeUnit.SECONDS);
 return false;
 }

 redis.delete(key); // 校验成功后立刻作废
 return true;
}

四个最常见的坑

校验成功后忘了删除 key——同一个验证码能复用，等于没校验
校验失败时直接覆写 key——重置了 TTL，攻击者可以"持续小流量爆破"
校验失败计数与原 record 分开存储——产生不一致，要么放一起要么用 Lua 原子更新
getExpire 边界值没兜底——Redis 在 key 不存在时返回 -2、无 TTL 时返回 -1，照搬当 TTL 用会出问题（上面代码已加兜底）

更稳妥的版本是用 Lua 脚本一次性完成"读取 + 比对 + 计数 + 保留 TTL"——彻底避免上面这些时序坑：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


-- KEYS[1]=验证码 key, ARGV[1]=用户输入
local v = redis.call('GET', KEYS[1])
if not v then return -1 end -- 已过期
local r = cjson.decode(v)
if r.failCount >= 5 then
 redis.call('DEL', KEYS[1])
 return -2 -- 锁定
end
if r.code == ARGV[1] then
 redis.call('DEL', KEYS[1])
 return 1 -- 成功
end
r.failCount = r.failCount + 1
local ttl = redis.call('TTL', KEYS[1]) -- 保留剩余 TTL
redis.call('SET', KEYS[1], cjson.encode(r), 'EX', ttl > 0 and ttl or 1)
return 0 -- 失败

七、典型事故回顾

事故 1：短信轰炸

某创业公司 0 限流上线，凌晨被脚本攻击——一晚发出 8 万条短信，短信通道账户余额清零，第二天用户登录时发不出短信。

教训：任何对外发短信的接口必须先有限流，哪怕是日活 10 的小项目。

事故 2：验证码被复用

注册接口的验证码校验后没删 key，研发以为"反正 5 分钟会过期"。攻击者发现后5 分钟内反复用同一验证码注册不同账号，刷出几千个假账号。

教训：验证码是一次性的，校验后立刻 DEL。

事故 3：跨场景复用

登录场景和找回密码用同一个 Redis key。攻击者通过"找回密码"功能拿到验证码，直接拿来登录目标账号——因为后端没区分。

教训：场景必须隔离，key 里带 scene。

事故 4：被竞争对手刷光额度

同一个手机号每分钟能发一次，攻击者每分钟刷一次，正常用户的请求被冷却时间挡住。

教训：单手机号也要有日发送上限，不只是冷却时间。

八、邮箱验证码的差异

邮箱验证码和短信思路类似，但有几个关键差别：

维度	短信	邮箱
成本	高（每条几分钱）	极低
触达速度	秒级	分钟级（垃圾邮件、延迟）
可靠性	高（运营商）	中（垃圾箱、屏蔽）
长度建议	6 位数字	6 位字母数字混合
防刷优先级	高（成本敏感）	中
用户体验	通常好	经常被丢进垃圾箱

邮箱可以用更长的验证码（甚至链接式），因为复制粘贴方便；短信必须短，因为人手输入。

邮箱链接式校验（点击链接验证）的好处是：可以包含完整 token，避免用户手输错。但要注意 token 一次性。

九、其他增强项

1. 验证码不要在响应里返回

测试代码里偶尔为了方便会返回 code 给前端——上线前一定要删干净。生产环境的验证码只能从用户终端获取。

2. 日志脱敏

1
2


log.info("send sms to {}", phone); // ❌ 完整手机号
log.info("send sms to {}", maskPhone(phone)); // ✓ 138****8000

完整手机号留在日志里，运维拉去做大数据分析时容易出"内部数据泄漏"事故。

3. 短信通道熔断

阿里云、腾讯云的短信网关偶尔抽风。一个通道连续失败 N 次后自动切换到备用通道：

1
2
3
4
5


List<SmsProvider> providers = List.of(aliyun, tencent, huawei);
for (SmsProvider p : providers) {
 if (p.isHealthy() && p.send(phone, code)) return true;
}
return false;

4. 监控告警

至少要有：

验证码发送 QPS 监控
失败率监控（>5% 报警）
校验失败率监控（>30% 报警，可能在被爆破）
单 IP 高频请求告警

十、一份生产级 Checklist

发布前对照这份清单逐条 check：

验证码用 SecureRandom 生成
Redis key 带 scene，绝不跨场景复用
TTL 5 分钟（不要更长）
同手机号 60 秒间隔
同手机号每天 ≤ 10 条
同 IP 每小时 ≤ 20 次
全局每分钟总量阈值
频繁请求触发滑块校验
校验成功立刻 DEL
校验失败次数 ≥ 5 直接锁定
校验失败时 TTL 不被重置
接口响应里不返回 code
日志里手机号脱敏
短信通道有 fallback
QPS 和失败率都有监控告警

少做任何一条都可能在某一天变成事故。

小结

把全文压一句：

验证码的难度从来不在『生成 6 位数字』，而在『当系统被恶意调用时，仍然能保护用户、保护成本、不影响正常体验』。

记住三个原则：

任何对外发短信的接口必须有限流——这是底线
验证码是一次性的，校验后立刻删
场景必须隔离，不要跨业务复用 key

把这三条做对，再叠加多维限流和人机校验，你的验证码系统就基本不会被薅羊毛了。

几种数据权限控制方案的探索与最佳实践

Sat, 09 Jul 2022 16:30:00 +0800

数据权限是什么，为什么麻烦

很多人混淆"权限"的两个层面：

功能权限（菜单/按钮/接口能不能访问）——一般用 RBAC 解决，前端隐藏菜单 + 后端拦截器校验角色
数据权限（同一个接口看到的数据范围不同）——更隐蔽、更难做对、出问题更严重

举个最常见的例子：

销售经理 A 调 /orders 接口，应该只看到自己团队的订单；销售经理 B 调同一个接口，应该只看到自己团队的；总监能看到全部。

接口完全相同，入参完全相同，但每个人看到的数据不一样。这就是数据权限。

数据权限做错了通常造成两类问题：

越权（漏数据）：用户看到了不该看到的（合规事故、信息泄漏）
过滤（少数据）：用户该看到却看不到（业务投诉）

下面把工程里常见的几种方案过一遍，从最朴素到最优雅。

方案一：在业务方法里硬写过滤条件

最朴素的写法——在每个查询接口里手动加 where：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public List<Order> queryOrders(OrderQuery q) {
 Long currentUserId = UserContext.current().getUserId();
 String role = UserContext.current().getRole();

 if ("ADMIN".equals(role)) {
 // 看全部
 } else if ("MANAGER".equals(role)) {
 q.setTeamId(getMyTeamId(currentUserId));
 } else {
 q.setOwnerUserId(currentUserId);
 }
 return orderMapper.selectByQuery(q);
}

它的问题：

重复劳动——每个查询接口都要写一遍这套判断
极易漏写——新增接口忘了加权限，瞬间漏数据
业务和权限耦合——业务代码看不清，“业务逻辑 + 权限逻辑"混在一起
角色变更代价大——新加一种角色要改几十处接口

生产环境永远不应该这样写。 但它是所有数据权限故事的起点——理解了它的痛，才能理解后面方案的价值。

方案二：注解 + AOP 拦截

把"这个接口受数据权限控制"变成一个声明：

1
2
3
4


@DataScope(scopeType = "ORDER", deptColumn = "dept_id", userColumn = "owner_id")
public List<Order> queryOrders(OrderQuery q) {
 return orderMapper.selectByQuery(q);
}

切面在方法执行前，根据当前用户的角色和数据权限规则，把对应的过滤条件塞到查询参数里：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@Around("@annotation(scope)")
public Object inject(ProceedingJoinPoint pjp, DataScope scope) throws Throwable {
 Object[] args = pjp.getArgs();
 for (Object arg : args) {
 if (arg instanceof BaseQuery q) {
 String filter = buildFilter(scope);
 q.setDataScopeSql(filter); // 塞条件
 }
 }
 return pjp.proceed();
}

private String buildFilter(DataScope scope) {
 User u = UserContext.current();
 if (u.hasRole("ADMIN")) return "";
 if (u.hasRole("MANAGER")) {
 return scope.deptColumn() + " IN (" + getDeptIds(u) + ")";
 }
 return scope.userColumn() + " = " + u.getUserId();
}

XML 里把条件塞进 SQL：

1
2
3
4
5
6
7
8
9


<select id="selectByQuery" parameterType="OrderQuery" resultType="Order">
 SELECT * FROM orders
 <where>
 <if test="status != null">AND status = #{status}</if>
 <if test="dataScopeSql != null and dataScopeSql != ''">
 AND ${dataScopeSql}
 </if>
 </where>
</select>

这是 若依（RuoYi）等开源后台管理系统的经典做法。

它的优劣

优点：

业务代码干净——只多一个注解
权限规则集中——所有角色判断都在切面里
接入新接口成本低

缺点：

${...} 拼接字符串——SQL 注入风险，必须严格清理输入
强依赖业务参数对象的字段——setDataScopeSql 要在每个 Query 上都有
AOP 时机偏晚——不是真正的"对所有 SQL 通用”，跨表 join、子查询场景容易漏

方案三：MyBatis 拦截器改写 SQL

更通用的姿势——直接在 SQL 执行前改写它。MyBatis 的 Interceptor 可以拦截 Executor.query，拿到原始 SQL 后用 SQL 解析器（Druid / JSqlParser）改写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


@Intercepts({
 @Signature(type = StatementHandler.class, method = "prepare", args = {Connection.class, Integer.class})
})
public class DataScopeInterceptor implements Interceptor {

 @Override
 public Object intercept(Invocation invocation) throws Throwable {
 StatementHandler sh = (StatementHandler) invocation.getTarget();
 BoundSql boundSql = sh.getBoundSql();

 String origin = boundSql.getSql();
 String rewritten = rewrite(origin);
 ReflectUtil.setField(boundSql, "sql", rewritten);
 return invocation.proceed();
 }

 private String rewrite(String sql) {
 // 用 JSqlParser 解析，识别要保护的表，加上 where
 Statement stmt = CCJSqlParserUtil.parse(sql);
 // 遍历所有 SELECT，检测到包含 orders 表时附加 dept_id IN (...)
 // ...
 return modified;
 }
}

MyBatis-Plus 的多租户、数据权限插件都是这个思路：

1
2
3
4
5
6


public class TenantSqlParser implements ISqlParser {
 @Override
 public SqlInfo processParser(Statement statement, ...) {
 // 自动给 SELECT/UPDATE/DELETE 加上 tenant_id = ?
 }
}

它的优劣

优点：

覆盖所有 SQL——不管 Mapper 怎么写，最终改写的是真正执行的 SQL
业务零侵入——不需要加注解、不需要改 Mapper
能处理 join、子查询——SQL 解析器懂语法树

缺点：

实现复杂——JSqlParser 要熟，否则改写错了就 SQL 报错
性能开销——每条 SQL 都过一遍解析器（不过相对 DB 耗时可忽略）
白名单/黑名单维护——不是所有表都受数据权限限制（系统配置表、字典表），要有规则识别

方案四：多租户场景的"自动 tenant_id"

如果你的数据权限本质就是"按租户隔离"，可以更简单——所有表都加一个 tenant_id 字段，所有 SQL 都自动带上 WHERE tenant_id = ?。

MyBatis-Plus 的实现方式：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


@Bean
public MybatisPlusInterceptor mpInterceptor() {
 MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
 interceptor.addInnerInterceptor(new TenantLineInnerInterceptor(new TenantLineHandler() {
 @Override public Expression getTenantId() {
 return new LongValue(UserContext.current().getTenantId());
 }
 @Override public boolean ignoreTable(String tableName) {
 return Arrays.asList("sys_dict", "sys_config").contains(tableName);
 }
 }));
 return interceptor;
}

之后所有查询自动带 tenant_id，包括子查询和 join 内部。

这是 SaaS 系统数据隔离的事实标准。

方案五：基于行级安全（RLS）的数据库原生方案

Postgres / Oracle 都支持 Row-Level Security，可以让数据库根据"当前 session 的标识"自动过滤行：

1
2
3
4
5
6
7
8


-- Postgres
ALTER TABLE orders ENABLE ROW LEVEL SECURITY;

CREATE POLICY tenant_isolation ON orders
 USING (tenant_id = current_setting('app.tenant_id')::bigint);

-- 应用每次连接后设置 session 变量
SET app.tenant_id = 123;

优势：从数据库层杜绝越权，业务代码完全无感，连忘记加权限的可能都没有。

劣势：

MySQL 不原生支持（要靠 view + trigger 模拟，复杂）
需要在每次拿连接后设置 session（连接池场景要小心）
数据库故障时业务排查多一层
跨 DB 厂商兼容性差

金融、医疗等强合规场景值得用，普通业务大可不必。

设计层面：数据权限模型怎么搞

不论用哪种实现方案，数据权限的核心是『谁、对什么数据、有什么操作权』。常见模型：

1. 基于部门/组织树

1
2
3
4
5


公司
├─ 销售一部
│ ├─ A 组
│ └─ B 组
└─ 销售二部

权限范围一般有 4 种：

本人：owner_id = currentUserId
本部门：dept_id = currentDeptId
本部门及子部门：dept_id IN (currentDept + 所有子部门)
全部

实现关键是部门树要有层级关系——通常每个 dept 表里有 parent_id 加 path（如 /1/3/8/），子部门用 LIKE 查就行：

1

WHERE dept.path LIKE '/1/3/%'

2. 基于自定义数据范围

部门模型不够灵活时，加一张"用户数据范围表"：

user_id	data_scope_type	data_scope_value
100	DEPT	1,2,3
100	OWNER	self
200	ALL	-

权限灵活但配置复杂度上升。

3. 基于策略（Policy）

更进阶——每条策略描述"什么角色能看什么条件下的什么数据"：

1
2
3
4
5
6
7


policies:
 - role: SALES_MANAGER
 resource: order
 scope: "dept_id IN ${myDept + childDept}"
 - role: FINANCE
 resource: order
 scope: "amount > 0 AND status != 'DRAFT'"

这是大型系统、SaaS 平台的做法，但对中小项目过度设计。

工程上的实战建议

flowchart TD
 Start([需要做数据权限?])
 Start --> Type{什么类型?}
 Type -->|租户隔离| MT[MP TenantLine 插件
所有 SQL 自动加 tenant_id]
 Type -->|按部门看数据| Mode{规则简单 or 复杂?}
 Mode -->|简单 4 种范围| AOP[注解 + AOP + Query 字段]
 Mode -->|复杂自由组合| Interceptor[MyBatis 拦截器 + JSqlParser 改写]
 Type -->|强合规要求| RLS[数据库 RLS]

具体几条建议：

先理清模型再写代码——画清楚"角色 → 范围 → 表"的对应表
优先选侵入小的方案——MyBatis 拦截器 / MP 多租户插件好过 AOP，AOP 好过硬编码
白名单和黑名单要明确——字典表、系统配置表不应该被权限过滤；防止"管理员配置了字典却看不到"
失败要"看不到"而不是"报错"——越权应该是"你不该看到的就直接没返回"，不是抛异常告诉攻击者"你越权了"
测试用例必须覆盖——每种角色都要专门测试：A 角色看到的、不该看到的、边界数据
审计日志必须打——重要查询的"用户身份 + 看到的数据范围"要记录，事后追溯
写操作也要校验——别只做查询权限；UPDATE/DELETE 一样要校验"这条数据是不是这个用户能改的"

小结

数据权限做对的关键不在框架选型，在模型抽象和工程纪律。

把全文压一句：

数据权限是『隐式过滤』——业务代码不该感知它，但它必须无处不在。

不同规模的项目对应方案：

小项目、固定几种角色 → 注解 + AOP，把规则集中起来
多租户 SaaS → MP TenantLine 插件，零侵入自动隔离
复杂角色 × 部门 × 自定义范围 → MyBatis 拦截器 + JSqlParser 自动改写
强合规 → 数据库 RLS

不管哪一种，让"忘记加权限"在架构上不可能发生——这才是真正的数据权限设计。

Spring Boot 中被低估的扩展点——EnvironmentPostProcessor

Fri, 12 Nov 2021 15:30:00 +0800

一个真实的烦恼

每个上规模的项目都会遇到这种需求：

启动时要从某个外部源（密钥管理系统、配置中心、加密的 KMS）拿配置
配置要在 Spring 启动最早期就生效，因为后面的 Bean 初始化都依赖它
不能改业务代码——业务代码里只想看到普通的 @Value("${db.password}")

最常见的几种做法：

@Value：太晚，只能取已经加载好的属性
@PropertySource：能加载文件，但支持不了复杂逻辑（解密、调远程服务）
手动在 main 里 set：丑陋且和 Spring 配置体系脱节
写一个 @PostConstruct：太晚——很多 Bean（如数据源）已经基于错误密码初始化失败了

正确答案是 Spring Boot 提供的一个相对"冷门但极其关键"的扩展点——EnvironmentPostProcessor。

它是什么，处于什么位置

Spring Boot 的启动过程里，最早能干预配置的扩展点就是它：

flowchart TD
 A[SpringApplication.run] --> B[加载 spring.factories / SPI]
 B --> C[准备 Environment]
 C --> D["应用 EnvironmentPostProcessor
(每个 Processor 拿到 Environment 都能读、能加、能改)"]
 D --> E["@PropertySource 加载、application.yml 加载"]
 E --> F[ApplicationContext 创建]
 F --> G[Bean 初始化（含 @Value / @ConfigurationProperties）]

关键时机：

比 application.yml 加载完之后（你能读到已有配置）
比 Bean 初始化之前（你的修改对 @Value 全部生效）

也就是说——它是 Spring 配置体系的最后一道"前置插入点"。

一个最小可运行的例子

我们假设要做一件事：启动时根据 spring.profiles.active 自动注入一组运行时元数据（机器名、IP、构建版本号等）。

步骤 1：写一个 EnvironmentPostProcessor

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


public class RuntimeMetaPostProcessor implements EnvironmentPostProcessor, Ordered {

 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 Map<String, Object> meta = new HashMap<>();
 meta.put("runtime.host", getHostName());
 meta.put("runtime.ip", getHostAddress());
 meta.put("runtime.startedAt", LocalDateTime.now().toString());
 meta.put("runtime.jvmVersion", System.getProperty("java.version"));

 // 把这些值作为最高优先级 PropertySource 注入
 env.getPropertySources().addFirst(new MapPropertySource("runtime-meta", meta));
 }

 @Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE + 10; }

 private String getHostName() {
 try { return InetAddress.getLocalHost().getHostName(); }
 catch (Exception e) { return "unknown"; }
 }
 private String getHostAddress() {
 try { return InetAddress.getLocalHost().getHostAddress(); }
 catch (Exception e) { return "unknown"; }
 }
}

步骤 2：注册

src/main/resources/META-INF/spring.factories（Spring Boot 2.x）：

1
2


org.springframework.boot.env.EnvironmentPostProcessor=\
com.app.config.RuntimeMetaPostProcessor

Spring Boot 3.x 改用 META-INF/spring/org.springframework.boot.env.EnvironmentPostProcessor.imports：

1

com.app.config.RuntimeMetaPostProcessor

步骤 3：业务里随便用

1
2
3
4
5


@Value("${runtime.host}")
private String host;

@Value("${runtime.ip}")
private String ip;

启动看到效果：

1
2
3


runtime.host=DESKTOP-ABC123
runtime.ip=192.168.1.101
runtime.startedAt=2021-11-12T15:30:11

它最有价值的几个真实场景

场景 1：数据库密码从 KMS / Vault 解密

业务里 application.yml 写的是密文，启动时解密后塞回去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public class DecryptPostProcessor implements EnvironmentPostProcessor {

 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String encrypted = env.getProperty("spring.datasource.password");
 if (encrypted != null && encrypted.startsWith("ENC(")) {
 String decrypted = decryptFromKms(encrypted);
 Map<String, Object> map = Map.of("spring.datasource.password", decrypted);
 env.getPropertySources().addFirst(new MapPropertySource("decrypted", map));
 }
 }
}

业务代码完全不知道密码加密过——这是它最干净的姿势。

场景 2：从配置中心拉配置

虽然 Spring Cloud Config / Nacos / Apollo 都有自己的 starter，但它们底层就是基于 EnvironmentPostProcessor / BootstrapContext 实现的。理解这个扩展点，你就能看懂这些组件的源码逻辑。

例如自己写一个最小的"远程配置中心客户端"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


public class RemoteConfigPostProcessor implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String app_id = env.getProperty("app.id");
 String env_name = env.getProperty("spring.profiles.active", "dev");

 Map<String, Object> remote = fetchFromRemote(app_id, env_name);
 env.getPropertySources().addLast(new MapPropertySource("remote-config", remote));
 }
}

addLast 的语义是"远程配置优先级低于本地"——本地能覆盖远程；反过来 addFirst 是"远程覆盖本地"。位置选择是核心设计决策。

场景 3：开发/测试自动开启功能开关

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


public class DevModePostProcessor implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 String[] active = env.getActiveProfiles();
 if (Arrays.asList(active).contains("dev")) {
 Map<String, Object> overrides = Map.of(
 "logging.level.com.app", "DEBUG",
 "spring.jpa.show-sql", "true",
 "feature.mock-payment", "true"
 );
 env.getPropertySources().addFirst(new MapPropertySource("dev-overrides", overrides));
 }
 }
}

业务代码都不需要看到这些开关，开发模式自动开启。

场景 4：从环境变量适配老配置 key 名

公司迁移老系统时，老的 K8s ConfigMap 用的是 DB_USER、DB_PASSWORD，新的 Spring Boot 期望 spring.datasource.username、spring.datasource.password：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public class LegacyEnvAdapter implements EnvironmentPostProcessor {
 @Override
 public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 Map<String, Object> map = new HashMap<>();
 if (env.getProperty("DB_USER") != null) {
 map.put("spring.datasource.username", env.getProperty("DB_USER"));
 }
 if (env.getProperty("DB_PASSWORD") != null) {
 map.put("spring.datasource.password", env.getProperty("DB_PASSWORD"));
 }
 if (!map.isEmpty()) {
 env.getPropertySources().addFirst(new MapPropertySource("legacy-adapter", map));
 }
 }
}

老的 ConfigMap 不动，新代码跑得起来。

与其他扩展点的对比

扩展点	触发时机	适用场景
`EnvironmentPostProcessor`	Environment 准备完之后	配置加载/改写
`ApplicationContextInitializer`	Context 创建之前	给 Context 注册 BeanDefinition
`BeanFactoryPostProcessor`	BeanDefinition 加载完	修改/新增 BeanDefinition
`BeanPostProcessor`	Bean 初始化前后	对 Bean 做增强（AOP 基础）
`ApplicationListener`	各种生命周期事件	监听启动/关闭
`@PostConstruct`	Bean 初始化完成	单 Bean 的初始化逻辑

只关心配置时，永远用 EnvironmentPostProcessor，其它扩展点就不要拿来挪用。

几个关键细节

1. Order 决定多个 Processor 的执行顺序

如果项目里有多个 Processor（比如解密 + 远程拉取 + 适配老配置），它们的执行顺序由 getOrder() 决定，值小的先执行。

1

@Override public int getOrder() { return Ordered.HIGHEST_PRECEDENCE + 10; }

业务自己的 Processor 应该排在框架的 Processor 之后——HIGHEST_PRECEDENCE 是 Integer.MIN_VALUE，加一点偏移避免和框架抢顺序。

2. PropertySource 的优先级

Environment 维护了一个有序的 PropertySource 列表：

flowchart LR
 A["addFirst
最高优先级"] --> B["命令行参数"] --> C["application.yml"] --> D["environment 变量"] --> E["addLast
最低优先级"]

加自定义 source 时关键决策是 addFirst 还是 addLast：

解密类、Override 类 → addFirst（自己的值优先）
远程 fallback 配置 → addLast（被本地优先）

写错位置会导致"为什么我设置了配置不生效？“这种排查噩梦。

3. 不要在 Processor 里依赖 Spring Bean

EnvironmentPostProcessor 触发时整个 ApplicationContext 还没建好——你不能 @Autowired，不能用 Spring Bean。需要的工具类要么自己 new，要么用静态工厂方法。

4. 异常处理

Processor 里抛异常会让整个应用启动失败。像"远程配置中心拉取失败"这种外部依赖应该有 fallback 行为：

1
2
3
4
5
6
7


try {
 Map<String, Object> remote = fetchFromRemote(...);
 env.getPropertySources().addLast(...);
} catch (Exception e) {
 log.warn("remote config unavailable, fallback to local", e);
 // 不重抛，让应用用本地配置启动
}

5. 日志：Processor 太早，标准 logback 还没初始化

Processor 触发时 logback / log4j2 通常还没初始化好，写日志可能丢失。一个 workaround 是用 DeferredLog：

1
2
3
4
5
6
7
8


private static final DeferredLog log = new DeferredLog();

@Override
public void postProcessEnvironment(ConfigurableEnvironment env, SpringApplication app) {
 log.info("decrypting config...");
 // ...
 app.addInitializers(ctx -> log.replayTo(MyProcessor.class));
}

DeferredLog 把日志先缓存起来，等 logging 体系准备好后回放。生产代码里强烈建议用它。

调试技巧

启动时把 Environment 的所有 PropertySource 打出来看一下：

1
2
3


((ConfigurableEnvironment) env).getPropertySources().forEach(ps -> {
 log.info("PropertySource: {}", ps.getName());
});

更简单的办法是开 Spring Boot Actuator 的 /actuator/env，能看到每个 key 的来源——调试配置加载顺序，没有比这更快的方法。

小结

一句话总结：

EnvironmentPostProcessor 是 Spring Boot 配置体系的最后一道前置插入点——业务代码里看到的每一个 @Value，最终值都可以由它在最早期被改写。

什么时候用：

启动时要做"配置改写、解密、远程拉取、key 适配”
业务代码不应该感知这些"配置层操作"
触发时机必须早于 Bean 初始化

写 Processor 的几个原则：

addFirst vs addLast 看清楚——这是最大的坑
不依赖 Spring Bean，触发时还没有 ApplicationContext
用 DeferredLog，正常 logger 不一定准备好
异常要有 fallback，别让外部依赖卡死启动
用 getOrder() 控制多 Processor 顺序

把这个扩展点用熟，你就能优雅地解决很多原本只能"在 main 里 hack"的奇葩需求。

给数据加上语义——JSON-LD 入门

Wed, 04 Aug 2021 15:30:00 +0800

一段看似差不多的代码

JSON 这种数据：

1
2
3
4
5


{
 "name": "鲁迅",
 "birthDate": "1881-09-25",
 "occupation": "Writer"
}

JSON-LD 这种数据：

1
2
3
4
5
6
7


{
 "@context": "https://schema.org",
 "@type": "Person",
 "name": "鲁迅",
 "birthDate": "1881-09-25",
 "occupation": "Writer"
}

肉眼看几乎一样——多了 @context 和 @type 两行。但它们做的事在量级上完全不同：

JSON 让机器能读这段数据
JSON-LD 让机器能理解这段数据是关于一个 Person 的

理解这个差别，是看懂"语义网"、“结构化数据 SEO”、“知识图谱"为什么需要 JSON-LD 的关键。本文把 JSON 和 JSON-LD 的差异、JSON-LD 的本质、它的真实落地场景讲清楚。

一、JSON 缺了什么

JSON 是非常成功的数据交换格式——简单、轻量、跨语言。但它有一个根本缺陷：

JSON 描述了数据的结构，不描述数据的语义。

举个具体例子：

1

{ "name": "李华", "age": 30 }

这段 JSON 里——

“name” 是什么意思？人的名字？产品的名字？文件名？
“age” 是数字"30 岁"还是 30 天 / 30 个月？
“李华” 是个人，还是品牌名，还是化名？

机器只看到字符串和数字，没法做任何"理解"层面的事。

如果两个系统要交换数据，他们必须事先约定每个字段的含义——这正是为什么数据集成、API 对接永远那么痛苦：每对接一个新系统都要写文档、对齐字段。

二、JSON-LD 怎么解决这个问题

JSON-LD（JSON for Linked Data）由 W3C 标准化，给 JSON 加了"语义层”：每个字段都引用一个公开 URI 定义的"概念"。

1
2
3
4
5
6


{
 "@context": "https://schema.org",
 "@type": "Person",
 "name": "鲁迅",
 "birthDate": "1881-09-25"
}

@context: https://schema.org —— 告诉机器：“本文档使用 Schema.org 词汇表”
@type: Person —— 告诉机器：“本对象是一个 Schema.org 定义的 Person”
name、birthDate —— 这些字段在 Schema.org 中有明确定义

任何机器（搜索引擎、抓取器、知识图谱）拿到这段数据后，只要它支持 Schema.org，就立刻知道这是一个人，name 是人的姓名，birthDate 是人的出生日期。

不需要事先约定。不需要写文档。语义来自 URI。

三、JSON-LD 的核心机制

JSON-LD 主要靠四个 @ 关键字：

1. `@context`：上下文

声明数据使用的词汇体系。最重要的关键字：

1

"@context": "https://schema.org"

也可以自定义：

1
2
3
4


"@context": {
 "name": "http://example.com/vocab#fullName",
 "age": "http://example.com/vocab#yearsOld"
}

每个 key 都映射到一个 URI——这就是"语义"的来源。

2. `@type`：类型

告诉机器这个对象是"什么"：

1
2
3


"@type": "Person"
"@type": "Product"
"@type": "Organization"

3. `@id`：标识符

为对象提供一个唯一标识（通常是 URI）：

1
2
3
4
5


{
 "@id": "https://example.com/person/lingcoder",
 "@type": "Person",
 "name": "lingcoder"
}

@id 让两条 JSON-LD 数据可以引用同一个实体——这是构建知识图谱的基础。

4. `@graph`：多对象集合

一个文档里描述多个对象：

1
2
3
4
5
6
7


{
 "@context": "https://schema.org",
 "@graph": [
 { "@type": "Person", "@id": "#zhang", "name": "张三" },
 { "@type": "Organization", "@id": "#abc", "name": "ABC 公司" }
 ]
}

四、关联数据（Linked Data）：JSON-LD 的真正价值

JSON-LD 的"LD"是 Linked Data——让数据之间能相互引用、形成图：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


{
 "@context": "https://schema.org",
 "@type": "Article",
 "headline": "Spring Cloud 微服务实战",
 "author": {
 "@type": "Person",
 "@id": "https://example.com/person/lingcoder",
 "name": "lingcoder"
 },
 "publisher": {
 "@type": "Organization",
 "@id": "https://example.com/org/abc",
 "name": "ABC 出版社"
 }
}

文章 → 作者（Person）→ 出版社（Organization）——这些都是独立的实体，通过 @id 相互引用。

任何爬虫拿到这段数据后，自动知道：

有一个文章对象
它有一个 Person 作者
它有一个 Organization 出版社
这些实体可能也存在于其他网页上（通过 @id 关联）

这是"知识图谱"的本质——图就是节点 + 边，JSON-LD 把节点（@id）和边（关系）都标准化了。

五、JSON-LD 的真实落地场景

1. SEO 结构化数据（最普及）

Google / Bing / 百度都支持 JSON-LD 作为结构化数据格式。在 HTML 里加：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


<script type="application/ld+json">
{
 "@context": "https://schema.org",
 "@type": "Article",
 "headline": "JSON 与 JSON-LD",
 "author": {
 "@type": "Person",
 "name": "lingcoder"
 },
 "datePublished": "2021-08-04",
 "image": "https://example.com/cover.svg"
}
</script>

搜索引擎抓到这段后，能在搜索结果里展示富片段（rich snippet）——评分、价格、作者、发布时间——大大提升点击率。

flowchart LR
 Page[网页] --> SE[搜索引擎]
 SE --> Plain[普通搜索结果
纯文本摘要]
 Page -.JSON-LD.-> SE2[搜索引擎]
 SE2 --> Rich[富片段
评分/价格/作者]

这是 JSON-LD 在 Web 上最广泛、最实用的应用。

2. 知识图谱

学术领域的论文数据库、医疗领域的病例数据、电商的商品图谱——用 JSON-LD 把不同来源的数据串起来。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
 "@context": "https://schema.org",
 "@type": "MedicalCondition",
 "name": "糖尿病",
 "associatedAnatomy": { "@type": "AnatomicalStructure", "name": "胰腺" },
 "possibleTreatment": [
 { "@type": "Drug", "name": "胰岛素" },
 { "@type": "MedicalTherapy", "name": "饮食控制" }
 ]
}

3. Web3 / 去中心化身份

DID（Decentralized Identifier）和 Verifiable Credentials（VC）规范用 JSON-LD 描述身份和凭证：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "@context": [
 "https://www.w3.org/2018/credentials/v1",
 "https://www.w3.org/2018/credentials/examples/v1"
 ],
 "type": ["VerifiableCredential", "UniversityDegreeCredential"],
 "issuer": "did:example:university",
 "credentialSubject": {
 "id": "did:example:alice",
 "degree": { "type": "BachelorDegree", "name": "Bachelor of Science" }
 }
}

4. RDF 兼容

JSON-LD 直接可以转成 RDF 三元组——和学术界、政府开放数据互通。

六、JSON-LD vs Microdata vs RDFa

HTML 结构化数据三种主流格式：

	JSON-LD	Microdata	RDFa
写法	`<script>` 块	HTML 标签里加属性	HTML 标签里加属性
内嵌位置	任意	紧贴对应内容	紧贴对应内容
与内容耦合	解耦	强耦合	强耦合
谷歌推荐	首选	支持	支持
易维护	✓	△	△

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<!-- Microdata（侵入式） -->
<div itemscope itemtype="https://schema.org/Person">
 <span itemprop="name">鲁迅</span>
 <span itemprop="birthDate">1881-09-25</span>
</div>

<!-- JSON-LD（独立块） -->
<script type="application/ld+json">
{ "@context": "https://schema.org", "@type": "Person", ... }
</script>

Google 官方推荐 JSON-LD——和 HTML 结构解耦，易于运维，模板化生成方便。

七、几个工程实践

1. 不要手工写

JSON-LD 字段嵌套深、重复多——代码生成，别手写。Java 用 org.schema.javasdk，Node 用 schema-dts，能避免拼字段错。

2. 验证工具

写完用 Google Rich Results Test 验证——不验证就上线，搜索引擎抓不到富片段。

3. context 缓存

https://schema.org 是个真实的 URL，机器抓数据时会去访问。生产场景把 context 缓存在本地，避免延迟。

4. 不要塞业务字段

JSON-LD 是对外用——只放标准 Schema.org 字段。内部业务字段（数据库 ID、内部状态）不要塞进 JSON-LD，会污染语义。

5. SEO 价值的真实预期

加了 JSON-LD 不一定立刻有富片段——Google 决定是否展示，并不保证。但没加一定没有——成本极低，回报概率高，工程上是无脑加的事。

八、什么场景该用 JSON-LD

✅ 适合：

公开网页的结构化标注（最普及场景，做 SEO）
跨系统数据交换（标准化语义）
知识图谱构建
Web3 / DID / VC

❌ 不适合：

普通的 API 数据交换——用 JSON 就够了
内部系统通信——加 @context 是开销
性能敏感场景——JSON-LD 文档体积比 JSON 大

普通 API 用普通 JSON，只有"数据需要被外部理解"时上 JSON-LD。

小结

把全文压一句：

JSON 让机器读得到数据，JSON-LD 让机器读懂数据。前者解决传输，后者解决语义。

工程上的实践：

公开网页加 JSON-LD——SEO 富片段几乎无成本
用 Schema.org 词汇表，不要造私有词汇
用工具生成，用 Google Rich Results Test 验证
内部系统不必折腾——纯 JSON 就够

理解 JSON-LD 不是为了在每个项目里都用它，而是理解"语义网"为什么重要——当你下次要让机器"看懂"数据而不只是"读懂"时，知道有这件武器可用。

微服务通信用 OpenFeign 还是 Dubbo

Mon, 19 Jul 2021 16:00:00 +0800

一句话先把问题摆出来

服务之间应该用 HTTP 还是 RPC 通信？

这是任何一个 Java 微服务团队都绕不过去的选择。社区里两套生态各有铁粉：

Spring Cloud + OpenFeign：基于 HTTP/REST，整套 Spring 全家桶最自然的延伸
Apache Dubbo：阿里开源的 RPC 框架，国内大厂的事实标准

新人选型时常常陷入一个误区——纠结于"谁性能好"。但只看 QPS 这件事会让你错过更重要的因素：协议哲学、生态契合度、运维成本、组织能力。

本文把这两套方案的差异、各自优劣、以及不同场景下的选型建议讲清楚。

协议层：HTTP 与 RPC 的本质差异

OpenFeign：HTTP 客户端的"声明式"

Feign 的本质是对 HTTP 客户端的封装。你定义一个接口，加几个注解，Feign 用动态代理把方法调用翻译成 HTTP 请求：

1
2
3
4
5
6
7
8


@FeignClient(name = "order-service")
public interface OrderClient {
 @GetMapping("/orders/{id}")
 OrderVO getById(@PathVariable Long id);

 @PostMapping("/orders")
 OrderVO create(@RequestBody OrderCreateDTO dto);
}

调用方写起来像调本地方法：

1

OrderVO order = orderClient.getById(1001L);

但底层走的是标准 HTTP——序列化通常是 JSON，传输是文本，每次请求都有完整的 HTTP 头开销。所以 Feign 的本质就是一个"会的协议"被打包成"省心的姿势"。

Dubbo：原生 RPC

Dubbo 是为 RPC 而生的。客户端和服务端都是 Java，直接通过自定义的二进制协议（Dubbo 协议、Triple 协议等）传输 Java 对象。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


// 服务端
@DubboService
public class OrderServiceImpl implements OrderService {
 @Override public OrderVO getById(Long id) { ... }
}

// 调用端
@DubboReference
private OrderService orderService;

OrderVO order = orderService.getById(1001L);

注意——两端共享同一个接口（Java interface），通过注册中心拉到地址后建立长连接。没有 URL，没有 HTTP 头，序列化默认是 Hessian 或 Kryo（紧凑二进制）。

性能差距：到底差多少

实测数据（同机房、千兆内网、相同业务复杂度）：

指标	OpenFeign + Spring Cloud	Dubbo（默认 dubbo 协议）
单次 RTT	5-15 ms	1-3 ms
序列化大小	JSON，相对大	Hessian/Kryo，2-5 倍小
单连接 QPS	数千	数万
CPU 序列化开销	较高	较低

Dubbo 在性能上确实有显著优势——但请注意三点：

上述差距在"调用频率高、链路深"时才显著放大；多数业务一次接口调用 50-100ms，5ms 和 1ms 的差距完全淹没在业务里
Feign 改用 HTTP/2 + Protobuf 就能逼近 RPC 性能（Spring 6 / Spring Cloud 2022+ 支持）
性能问题大多在数据库、外部 API、缓存上，通信协议很少是瓶颈

不建议把『性能』当成选 Dubbo 的唯一理由。 如果你不能拿出一个真实的、被 Profiler 证实的、序列化耗时占主导的瓶颈，那性能差距对你来说几乎没意义。

生态契合度：谁配谁更顺手

维度	Spring Cloud + Feign	Dubbo
注册中心	Eureka / Nacos / Consul	Zookeeper / Nacos
配置中心	Spring Cloud Config / Nacos	Apollo / Nacos
网关	Spring Cloud Gateway	通常前置 Nginx + 业务网关
熔断	Resilience4j / Sentinel	Sentinel（原生集成）
链路追踪	Sleuth + Zipkin	Skywalking / 自建 Filter
服务治理	基础	强（路由、灰度、限流、调度都内置）
跨语言	天然 ✓（HTTP）	△（Triple 协议支持，gRPC 互通）
调试工具	Postman / curl 直接打	Telnet / Dubbo Admin

Spring Cloud 的强项是全家桶生态完整，Feign 只是其中一环；Dubbo 的强项是服务治理特性原生且强大——做到 Spring Cloud 同等治理能力，需要拼接一堆组件。

跨语言：被低估的因素

这是很多团队选型时最被低估的因素。

Feign 走 HTTP/REST：只要对方能发 HTTP 请求，谁都能调。Python、Go、Node 团队对接你的服务零门槛
Dubbo 默认是 Java-only：跨语言要切到 Triple 协议（基于 gRPC），配置和工具链都比 HTTP 复杂

如果你的组织是多语言团队——前端 Node、数据团队 Python、运营内部系统是 PHP——选 Feign 几乎没有疑问。强行用 Dubbo 让其他语言对接，会成为长期摩擦。

如果你的组织清一色 Java，跨语言不是问题，那 Dubbo 的劣势就消失了。

调试与可观测性

Feign 优势

HTTP 接口能直接用 Postman / curl 调试
浏览器开发工具能看请求响应
Nginx / 网关日志能直接读
Tcpdump / Wireshark 抓包能看明文

Dubbo 劣势

二进制协议要专用工具（Dubbo Admin、Telnet 命令）
Mock 和压测要起 Java 客户端
排查 “客户端发了什么” 比 HTTP 麻烦得多

1
2
3
4
5
6
7


# Feign 接口随时打：
curl http://order-service/orders/1001

# Dubbo 类似的事要用 telnet：
telnet 192.168.1.10 20880
ls com.xx.OrderService
invoke com.xx.OrderService.getById(1001)

可观测性是长期运维的核心痛点——调试方便程度对开发体验的影响远超 5ms 的性能差距。

学习曲线与团队上手成本

因素	Feign	Dubbo
新人上手	几乎零门槛（懂 HTTP 即可）	中等（注解 + 注册中心 + 协议）
大团队培训	简单	中等
调试体验	优	中
扩展定制	需懂 OkHttp / RestTemplate	需懂 Filter / Invoker SPI

新人入职第一周能用的是 Feign，三周后才能驾驭 Dubbo——团队规模一大，这个差距会成倍放大。

服务治理深度：Dubbo 的硬实力

如果说性能是 Dubbo 被高估的优势，那服务治理才是它真正的护城河。

Dubbo 原生支持的能力清单（Spring Cloud 多数都要拼装实现）：

多版本并行：@DubboReference(version = "1.0.0") 直接路由到指定版本服务
基于条件的路由规则：根据 Header / 参数 / 客户端 IP 路由到不同实例（灰度发布利器）
应用级 / 接口级粒度的治理
管理后台 Dubbo Admin 可视化调整路由、权重、限流，无需改代码
服务分组：环境/业务隔离

这些在 Spring Cloud 体系里要靠 Gateway + 自定义 Filter + Sentinel + Service Mesh 拼出来——能做，但维护成本高。

如果你做的是复杂的内部多团队协作系统（金融、电商核心链路），Dubbo 的治理能力会显著省心。

选型决策树

flowchart TD
 Start([选 Feign 还是 Dubbo?])
 Multi{多语言团队?}
 Start --> Multi
 Multi -->|是| Feign1[Feign / REST]
 Multi -->|否，纯 Java| Scale{服务规模?}
 Scale -->|小型，< 20 服务| Feign2[Feign / REST]
 Scale -->|中大型| Gov{是否需要复杂治理?
多版本/灰度/路由}
 Gov -->|不需要| Feign3[Feign 也够用]
 Gov -->|需要| Perf{对单次 RPC 性能敏感?}
 Perf -->|敏感| Dubbo1[Dubbo]
 Perf -->|不敏感| Choice[基于团队熟悉度选]

一些被反复争论的话题

争论 1：Spring Cloud 已经够强，Dubbo 没必要

部分对——如果你的业务复杂度还没碰到治理瓶颈，Spring Cloud 完全够。但有些治理特性（多版本、规则路由）原生 Spring Cloud 真的拼不出 Dubbo 那么顺手。

争论 2：Dubbo 把简单事情复杂化

部分对——Dubbo 的概念多（Provider/Consumer/Registry/Monitor，加上 Filter/Invoker/Cluster），新人确实一脸懵；但一旦上手，业务代码就和 Feign 一样简洁。

争论 3：现在该用 gRPC

gRPC 是个好选择，性能接近 Dubbo，跨语言天然支持。但生态在 Java 圈子相对薄弱——和 Spring 集成、注册中心选型、可观测性都要自己组装。Triple 协议（Dubbo 3）就是兼容 gRPC 的，意图是把"跨语言 + Dubbo 治理"一并拿下。

争论 4：直接用 Service Mesh

Mesh 把通信和治理下沉到 Sidecar，应用层只用最朴素的 HTTP/gRPC。理论上是终极方案，但运维 K8s + Istio 的复杂度让多数中小团队望而却步。

实战建议

我自己在团队里推的一份简版规则：

新启动的中小项目：直接 Spring Cloud + Feign。生态完整、上手快、调试方便，性能问题先不要担心
已有 Spring Cloud 体系的成熟团队：继续用 Feign，需要更高性能时点对点改 gRPC，不要整体迁 Dubbo
大量内部 Java 服务、纯 Java 技术栈、强治理需求：Dubbo（或 Dubbo 3）。多版本、灰度路由这些原生能力会省心
有跨语言需求：Feign / gRPC，不要 Dubbo（除非用 Triple）
绝不要"大力出奇迹"全家桶迁移：从 Spring Cloud 全部迁到 Dubbo 是高成本低收益的事，点对点重构才是务实做法

1
2
3
4
5
6


// 一个混合栈的例子：核心高频接口走 Dubbo，对外业务走 Feign
@FeignClient(name = "user-service")
public interface UserClient { ... } // 对外 / 跨语言

@DubboReference(version = "1.0.0")
private InventoryService inventory; // 内部高频

混合用没什么问题，只要团队两套都熟。

小结

把全文压成一句话：

OpenFeign 让通信变简单，Dubbo 让治理变强大。多数项目应当从 Feign 开始，治理瓶颈真正出现时再选择性引入 Dubbo——而不是反过来。

性能、生态、跨语言、调试、团队成本是五个真正影响选型的维度。别让"哪个性能好"这个伪问题误导你——通信协议很少是系统瓶颈，能让团队走得远的选择，永远是简单、可调试、生态完整的那一个。

微信扫码登录三种方案对比：开放平台、公众号、扫码即登录

Sun, 15 Nov 2020 16:30:00 +0800

用户体验决定一切

国内 Web 应用的登录方式里，微信扫码已经是事实标准——比手机号验证码更顺、不用记密码、用户基本人手都有微信。

但"微信扫码登录"实际上有好几种不同的方案，对应不同的用户体验和接入条件。新人接这块时常常分不清：

有的网站扫码后跳到微信"授权"页面再回来登录
有的网站扫码就完事了，不需要二次确认
有的扫码是公众号场景，扫完关注还能登录
有的是"网站二维码 + 用手机微信扫" → 登录 PC 端

每种背后用的是完全不同的微信能力。本文把三种主流姿势梳理清楚——微信开放平台 OAuth、公众号 OAuth、关注公众号即登录。

一、微信家族里的"应用类型"

要选对登录方案，先要搞清微信家的几类账号：

账号类型	适用场景
微信开放平台应用	网站、App 接入"使用微信登录"按钮
公众号（订阅号）	内容推送
公众号（服务号）	业务对接、可以做 OAuth 登录
微信小程序	小程序生态
企业微信应用	企业内部

我们要讲的扫码登录只涉及前两个——开放平台和服务号。

二、方案 A：微信开放平台 OAuth（PC 网站扫码）

最经典的"网页扫码登录"——你在 PC 端访问 12306 / 知乎 / 京东 PC 端，点"微信登录"，弹出二维码，手机微信扫一扫确认即可登录。

流程

sequenceDiagram
 Browser->>WebSite: 访问登录页
 WebSite->>WeChatOpen: redirect 二维码授权 URL
 WeChatOpen-->>Browser: 显示二维码
 Browser-->>Phone: 用户用手机微信扫
 Phone->>WeChatOpen: 扫码 + 确认
 WeChatOpen->>WebSite: redirect with code
 WebSite->>WeChatOpen: 用 code 换 access_token + openid
 WeChatOpen->>WebSite: 返回 token 和用户信息
 WebSite-->>Browser: 登录成功，set session

接入步骤

1. 在微信开放平台注册"网站应用"

登录 open.weixin.qq.com
创建网站应用，提交资质（要企业认证）
拿到 AppID 和 AppSecret

2. 前端跳转授权链接

1
2
3
4
5
6
7


const url = `https://open.weixin.qq.com/connect/qrconnect`
 + `?appid=${APP_ID}`
 + `&redirect_uri=${encodeURIComponent(CALLBACK)}`
 + `&response_type=code`
 + `&scope=snsapi_login`
 + `&state=${randomState}`;
window.location.href = url;

state 是 CSRF 防御——后端要校验回调时的 state 与前端发出的一致。

3. 后端用 code 换 access_token

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@GetMapping("/auth/wechat/callback")
public String callback(@RequestParam String code, @RequestParam String state) {
 // 校验 state（防 CSRF）
 if (!stateService.consume(state)) {
 throw new BusinessException("invalid state");
 }

 // 换 access_token
 String url = "https://api.weixin.qq.com/sns/oauth2/access_token"
 + "?appid=" + APP_ID
 + "&secret=" + APP_SECRET
 + "&code=" + code
 + "&grant_type=authorization_code";
 Map resp = restTemplate.getForObject(url, Map.class);
 // resp 里有 access_token, openid, unionid

 // 拉用户信息
 User user = userService.bindOrCreate((String) resp.get("openid"),
 (String) resp.get("unionid"));

 // 颁发自己的会话 token
 return "redirect:" + frontUrl + "?token=" + jwtService.issue(user);
}

关键点：openid vs unionid

openid：用户在这一个应用里的唯一标识——同一用户在你的 A 应用和 B 应用 openid 不同
unionid：用户在整个开发者账号下的唯一标识——同一开发者下所有应用共享

生产里通常以 unionid 作为主用户标识——避免"同一个微信用户在 PC 端和小程序里看起来是两个账号"。

三、方案 B：公众号 OAuth（关注后授权登录）

很多 H5 应用通过公众号入口登录——比如某些电商小程序的 H5 版本、某些活动落地页。

流程

用户在微信内打开你的网页 → 微信检测到是 H5 → 触发 OAuth → 不需要扫码（已是微信内）→ 用户授权 → 返回业务页面已登录。

sequenceDiagram
 User->>WeChat: 打开 H5 链接
 WeChat->>WebSite: 加载 H5
 WebSite->>OAuth: 跳到 OAuth 授权
 Note over OAuth: scope=snsapi_base 静默授权
scope=snsapi_userinfo 弹页面授权
 OAuth->>WebSite: 回调 with code
 WebSite->>WeChat API: code → openid (+ userinfo)
 WebSite->>User: 登录完成

snsapi_base vs snsapi_userinfo

公众号 OAuth 有两种 scope，差异很大：

	snsapi_base	snsapi_userinfo
用户感知	无（静默）	有授权页面
拿到信息	只有 openid	openid + 昵称 + 头像 + 城市等
适用场景	后台关联用户	显示头像/昵称

优先用 snsapi_base——拿到 openid 后查自己业务库即可，多数场景够用。只有真要展示用户头像昵称时才用 snsapi_userinfo——它会弹一个授权页打断流程。

接入要求

服务号（订阅号没有 OAuth 接口）
已认证（年费 300）
在公众号后台配置"网页授权域名"——只能在配置的域名下使用 OAuth
必须放一个微信验证文本到域名根目录

四、方案 C：关注公众号即登录（带场景值二维码）

这是最巧妙的一种——用户扫了带场景值的临时二维码、关注公众号后，公众号收到事件，后端推送登录态给前端。

业务侧体验是：“用户扫码并关注 → PC 端自动登录”——比 OAuth 少一次跳转。

整体架构

sequenceDiagram
 Browser->>Backend: 请求登录二维码
 Backend->>WeChat: 生成临时二维码（带 sceneId）
 WeChat-->>Backend: 返回 ticket
 Backend-->>Browser: 二维码图片
 Browser->>Browser: 长轮询 / SSE 等待登录
 Phone->>WeChat: 用户扫码
 WeChat->>Backend: 推送"扫码事件"
(包含 sceneId + openid)
 Backend->>Backend: sceneId 与会话关联，缓存 openid
 Browser->>Backend: 轮询查询 sceneId 状态
 Backend->>Browser: 返回登录信息

实现要点

1. 生成带 sceneId 的二维码

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


// 生成临时 sceneId（需要去重 + 过期）
String sceneId = generateUniqueSceneId();
sceneStore.put(sceneId, new SceneState(SceneStatus.PENDING), 5 * 60);

// 调微信接口生成 ticket
Map<String, Object> req = Map.of(
 "expire_seconds", 300,
 "action_name", "QR_STR_SCENE",
 "action_info", Map.of("scene", Map.of("scene_str", sceneId))
);
String ticket = callWeChatApi("/cgi-bin/qrcode/create", req);

// 返回前端：用 ticket 拼二维码 URL
String qrUrl = "https://mp.weixin.qq.com/cgi-bin/showqrcode?ticket=" + ticket;

2. 接收微信推送

公众号后台配置消息推送 URL，收到事件 callback：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@PostMapping("/wechat/callback")
public String onMessage(@RequestBody String xml) {
 WechatEvent event = parseXml(xml);
 if ("subscribe".equals(event.getEvent()) // 关注
 || "SCAN".equals(event.getEvent())) { // 已关注扫描
 String sceneId = event.getEventKey();
 String openid = event.getFromUserName();

 // 把扫码用户绑定到 sceneId
 sceneStore.update(sceneId, new SceneState(SceneStatus.SCANNED, openid));

 // 给用户回个欢迎语
 return buildReplyXml(openid, "登录成功！");
 }
 return "success";
}

3. 前端轮询或 SSE

1
2
3
4
5
6
7
8
9


const interval = setInterval(async () => {
 const resp = await fetch(`/auth/scan/check?sceneId=${sceneId}`);
 const data = await resp.json();
 if (data.status === 'SCANNED') {
 localStorage.setItem('token', data.token);
 location.href = '/dashboard';
 clearInterval(interval);
 }
}, 1500);

更优雅的姿势用 SSE 替代轮询——服务端扫码后主动推送。

这套方案的限制

要服务号，订阅号不行
subscribe 事件只在关注时触发——已关注用户扫码触发的是 SCAN，业务要分两种处理
临时二维码 5 分钟过期——前端要管理超时
场景值长度限制——临时二维码 scene_str 最多 64 字符

五、三种方案对比

	开放平台 OAuth	公众号 OAuth	公众号扫码即登录
适用场景	PC 网站	H5（微信内打开）	PC 网站（关注公众号）
资质	开放平台账号 + 企业	服务号 + 认证	服务号 + 认证
用户体验	扫码 → 授权确认 → 登录	自动跳转（snsapi_base 无感）	扫码 → 关注 → 登录
是否需关注	否	否	是
跳转步骤	多	一次	无（PC 端不跳）
适合做营销	否	是	是（强行涨粉）

六、实战建议

选型

flowchart TD
 Start([场景?])
 Start --> A{PC 网站登录?}
 A -->|是| B{要不要涨粉?}
 B -->|不要| O1[开放平台 OAuth]
 B -->|要涨粉| C[公众号扫码即登录]
 A -->|否，H5 微信内| O2[公众号 OAuth]

共性踩坑

1. 多账号体系

用户可能从 H5 / PC / 小程序多个端登录——用 unionid 统一身份，否则会有重复账号。

2. AppSecret 必须保密

永远不能暴露给前端——只在服务端用。前端拿到 code 后调自己后端，由后端去换 access_token。

3. 频率限制

微信 API 有调用频率限制（每天 N 次、每分钟 M 次），超额会被拒。生产要做：

access_token 缓存（2 小时有效，重复调用会被踢掉旧 token）
API 调用打日志，超频告警

4. 二维码缓存

每次生成新二维码都要调微信 API——前端每次刷新页面都生成新的会撞限制。建议给二维码加 1-2 分钟的客户端缓存。

5. 异常处理

用户在授权页面"取消"——回调还是会被调用，参数有差异
code 重复使用——只能用一次
access_token 过期——要刷新

6. 测试环境验证

微信不能跨域名调试——要么把测试环境配成独立公众号，要么用内网穿透。生产前一定在真实公众号下测过完整流程。

七、一些前沿姿势

微信小程序登录

如果你的业务要跨小程序 + H5 + PC 共享用户体系：

小程序：wx.login() + code2Session 拿 openid + unionid
H5：snsapi_base
PC：开放平台 OAuth

用 unionid 一统身份——前提是这些应用都挂在同一个开放平台账号下，否则 unionid 不互通。

跨端会话同步

PC 扫码登录后，移动端怎么也保持同步？通常是：

PC 拿到 token 后调一个"标记 unionid 已登录"接口
App / H5 启动时检查 unionid 是否处于"已登录"状态——是就静默登录

这是 12306 / 京东这类多端应用的常用做法。

小结

把全文压一句：

PC 网站用开放平台 OAuth；H5 微信内用公众号 OAuth；想顺带涨粉用『关注公众号即登录』。三者底层协议都是微信生态，但接入门槛、体验、营销价值差别很大。

工程上记住几条：

AppSecret 永远在服务端
用 unionid 统一身份
access_token 缓存 + 频率告警
state 防 CSRF
二维码加客户端缓存避免刷限额

把这套吃透，国内 Web 应用的"登录"问题基本就解决了。

Drools 与 Aviator：Java 业务规则引擎实战

Sat, 08 Aug 2020 15:30:00 +0800

业务规则总是变，代码总是改

每个长期运行的业务系统都会面对这种场景：

风控规则：“新用户首次下单超过 1000 元 → 拦截”——一周后调整阈值，要发版
优惠券规则：“订单满 500 减 50，且非周末”——节假日要变，要发版
积分规则：“VIP 用户购买电子产品 3 倍积分”——业务搞活动一变就要发版
审批规则：“金额 > 10 万走总监审批”——金额线一调就要发版

这些规则的共同特征是——规则本身经常变化，但发版周期至少几天。把规则硬编码进代码导致两个难题：

业务跟不上：规则等代码发版才生效
代码越改越烂：if-else 嵌十几层，谁也不敢动

社区有两个 Java 生态的常用工具：

Drools：重型规则引擎，DSL 强、推理能力强、有规则库
Aviator：轻量级表达式引擎，类似"加强版 SpEL"，编译执行速度极快

它们解决的问题在不同量级。本文讲清楚两者的定位、典型用法、踩坑点。

一、什么时候该用规则引擎

先把"该不该用"讲清楚。规则引擎不是银弹，盲目引入反而是负担：

✅ 适合用规则引擎：

规则数量多（几十到几百条）
规则经常变（业务/运营频繁调整）
规则需要业务/运营/产品自己改（不希望走开发流程）
规则之间有交叉（一条规则匹配影响其他规则）

❌ 不适合：

规则就 3-5 条，全年改不到一次
规则只能由开发改（那写代码就行）
性能极敏感（规则引擎再快也比硬编码慢）
团队没人懂规则引擎（运维/排查反而更难）

不要"为了用规则引擎而用"——多数中小项目用枚举 + 策略模式 + 配置中心就够了。

二、Aviator：轻量表达式引擎

它是什么

Aviator 是阿里开源的轻量级表达式引擎——本质是字符串表达式 + 上下文变量 → 求值：

1
2
3
4
5
6
7
8
9


import com.googlecode.aviator.AviatorEvaluator;

Map<String, Object> ctx = new HashMap<>();
ctx.put("amount", 1500);
ctx.put("vip", true);

Boolean ok = (Boolean) AviatorEvaluator.execute(
 "amount > 1000 && vip == true", ctx);
// ok = true

典型用法 1：动态阈值

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


// 规则配置在数据库 / Nacos
String expr = configService.get("risk.threshold.expr");
// "amount > 1000 || (newUser && amount > 500)"

Map<String, Object> ctx = Map.of(
 "amount", order.getAmount(),
 "newUser", user.isNew(),
 "vip", user.isVip()
);

if ((Boolean) AviatorEvaluator.execute(expr, ctx)) {
 throw new BusinessException("风控拦截");
}

阈值改动只改配置中心，不发版。

典型用法 2：动态计算公式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// "积分 = 金额 * 倍率 + 固定值"
String expr = "amount * rate + bonus";

Map<String, Object> ctx = Map.of(
 "amount", order.getAmount(),
 "rate", 0.1,
 "bonus", 10
);

Long points = ((Number) AviatorEvaluator.execute(expr, ctx)).longValue();

Aviator 的核心特性

语法接近 Java——+ - * / && || == != 都按 Java 语义
支持自定义函数

1
2
3
4
5
6
7
8
9


AviatorEvaluator.addFunction(new AbstractFunction() {
 public String getName() { return "isWeekend"; }
 public AviatorObject call(Map<String, Object> env, AviatorObject d) {
 LocalDate date = LocalDate.parse(((String) d.getValue(env)));
 return AviatorBoolean.valueOf(date.getDayOfWeek().getValue() >= 6);
 }
});

AviatorEvaluator.execute("isWeekend('2020-08-08')"); // true

预编译加速

1
2


Expression compiled = AviatorEvaluator.compile("amount > 1000 && vip");
compiled.execute(ctx); // 反复调用更快

极快——比 SpEL 快数倍

Aviator 的限制

没有"规则集"概念——你需要自己管理多条规则
没有 then 部分——只能算出布尔值或数值，没有"满足条件做什么"
不能推理——只是算单个表达式

Aviator 的本质是『把 if 条件部分抽出来变成字符串』——其余还是你自己写。

三、Drools：完整规则引擎

它是什么

Drools 是一套完整的规则引擎——基于 Rete 算法，把规则编译成决策图，能高效匹配大量规则。

它有自己的 DSL（DRL 文件）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


package com.example.rules;
import com.example.Order;

rule "新用户首单大额拦截"
 when
 $o: Order(amount > 1000, user.newUser == true)
 then
 $o.reject("新用户首单不能超过 1000");
end

rule "VIP 用户折扣"
 when
 $o: Order(user.vip == true, amount > 500)
 then
 $o.applyDiscount(0.9);
end

DRL 文件加载到 Drools 的 KieSession 里：

1
2
3
4
5
6
7


KieServices ks = KieServices.Factory.get();
KieContainer kc = ks.getKieClasspathContainer();
KieSession session = kc.newKieSession();

session.insert(order);
session.fireAllRules();
session.dispose();

fireAllRules() 会根据规则匹配自动执行所有命中的规则——这就是规则引擎的核心。

Drools 比 Aviator 强在哪

	Aviator	Drools
单条表达式	✓	✓（更复杂）
规则集合	✗	✓
条件 → 动作	✗	✓ when/then
规则间推理	✗	✓（Rete 算法）
优先级	✗	✓ salience
规则库管理	✗	✓ KieBase
业务可维护性	△ 程序员	✓ Drools Workbench / 工具
学习成本	低	高

Drools 的典型场景

复杂风控：100+ 条规则，规则之间有依赖
保险/金融：精算规则、产品定价规则
审批引擎：审批节点、条件分支
促销引擎：满减、买赠、阶梯优惠组合

Drools 的痛点

学习曲线陡——DRL 语法、KieSession、KieBase、AgendaGroup 等概念多
运维复杂——规则更新机制、Workbench 部署、版本管理
性能不一定快——Rete 算法在小规模规则下未必比 if-else 快
调试困难——规则匹配链条难追踪

不是所有"规则多变"的业务都需要 Drools。80% 的业务场景，Aviator + 配置中心就够了。

四、实战对比：同一个场景两种解法

需求：“订单金额满足条件时给折扣，规则可热更新”。

方案 A：Aviator + 配置中心

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


@Component
public class DiscountService {
 @Autowired private ConfigService configService;
 private Map<String, Expression> compiled = new ConcurrentHashMap<>();

 public BigDecimal calculate(Order order) {
 List<DiscountRule> rules = configService.getDiscountRules();
 for (DiscountRule rule : rules) {
 Expression expr = compiled.computeIfAbsent(
 rule.getId(),
 k -> AviatorEvaluator.compile(rule.getCondition()));
 
 Map<String, Object> ctx = buildContext(order);
 if ((Boolean) expr.execute(ctx)) {
 return order.getAmount().multiply(rule.getRate());
 }
 }
 return order.getAmount();
 }
}

DiscountRule 配置：

1
2
3
4
5
6


- id: vip_discount
 condition: "vip == true && amount > 500"
 rate: 0.9
- id: first_order
 condition: "newUser == true"
 rate: 0.95

优点：实现简单、学习成本极低、规则用 YAML / DB 随便配。

缺点：规则之间没有自动推理，必须按顺序匹配（开发自己 for 循环）。

方案 B：Drools

discount.drl：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


rule "VIP 折扣"
 salience 100
 when
 $o: Order(user.vip == true, amount > 500)
 then
 $o.setDiscountRate(0.9);
end

rule "首单折扣"
 salience 50
 when
 $o: Order(user.newUser == true)
 then
 $o.setDiscountRate(0.95);
end

salience 控制优先级——VIP 规则先于首单规则。

优点：规则之间能自动推理、能并行命中、可视化工具。

缺点：上手成本高、运维复杂、调试难。

五、选型决策

flowchart TD
 Start([需要把规则抽出来?])
 Start --> Count{规则有多少?}
 Count -->|< 30 条| Simple{业务/运营要自己改?}
 Count -->|>= 30 条且复杂| Complex{规则间有推理?}
 Simple -->|是| Aviator[Aviator + 配置中心]
 Simple -->|否| Code[直接代码 + 策略模式]
 Complex -->|有| Drools[Drools]
 Complex -->|没有| Aviator2[Aviator + 配置中心]

给一个直接的工程建议：

轻量场景优先 Aviator + 配置中心；只有规则数量上百、规则间有推理、且团队有人专门维护时，才值得引入 Drools 这种完整框架。

六、踩坑提醒

Aviator 篇

1. 表达式注入风险：用户输入直接执行表达式可能被构造恶意代码：

1
2
3


// ❌ 危险
String expr = userInput;
AviatorEvaluator.execute(expr);

要么白名单校验，要么把表达式只配在管理后台（运维/产品才能改）。

2. 类型转换：JSON 反序列化的 Number 在 Aviator 里可能是 Long 或 Double，比较时要小心：

1
2
3


ctx.put("amount", 100L);
AviatorEvaluator.execute("amount > 50.5", ctx); // ✓
AviatorEvaluator.execute("amount > 50", ctx); // ✓

3. null 安全：Aviator 默认对 null 比较会报错——要在表达式里 nil != amount && amount > 100。

4. 编译缓存：同一个表达式重复 execute 时一定要预编译，否则每次都重新解析。

Drools 篇

1. 内存里的规则：DRL 改了不会自动重载——要主动 reload KieBase。生产实践通常用 Drools Workbench 或自己实现热更新。

2. then 部分别写复杂逻辑：then 是 Java 代码，但塞太多业务逻辑会让规则文件膨胀。复杂动作应该放回 Service，then 只调一行。

3. fireAllRules 的副作用：规则的 then 段可能修改 fact，触发其他规则——容易陷入"规则套规则"的循环。用 no-loop true 关键字防止。

4. 性能：Rete 算法在规则少时反而慢——50 条以下用 Drools 收益不明显。

七、规则的版本与审计

不论用哪种引擎，生产规则都需要版本管理 + 审计：

每条规则有"最后修改人"、“修改时间”、“生效时间”
修改规则要走审批（运营 → 主管 → 上线）
上线前在测试环境验证（Dry Run）
生产环境支持快速回滚到上一版本

把这些做对，比规则引擎选什么都重要。

小结

把全文压一句：

业务规则要从代码里抽出来——简单场景 Aviator 一行表达式 + 配置中心，复杂决策 Drools 完整规则引擎，绝不要硬编码 if-else 然后频繁发版。

工程实践：

规则数量少 + 改动频率低 → 直接策略模式 + 配置
规则数量中等 + 业务运营要改 → Aviator
规则数量大 + 规则间有交叉 → Drools
规则一定要版本管理 + 审计——比引擎选型更重要

把规则与代码解耦，业务才能跑得动。

ExecutorCompletionService 与 CompletableFuture：场景与选型

Sat, 25 Apr 2020 16:30:00 +0800

一段几乎所有人都写过的反面代码

需要并发调用 5 个外部接口，最后聚合结果——多数人这么写：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


ExecutorService pool = Executors.newFixedThreadPool(5);
List<Future<Result>> futures = new ArrayList<>();
for (Task task : tasks) {
 futures.add(pool.submit(() -> callApi(task)));
}

List<Result> results = new ArrayList<>();
for (Future<Result> f : futures) {
 results.add(f.get()); // ★ 阻塞等
}

看起来挺合理。但有个性能陷阱——futures 的顺序是提交顺序，不是完成顺序。

假设 5 个接口耗时是：

接口	耗时
A	3s
B	1s
C	5s
D	2s
E	1s

写在 for 循环里 f.get() 时——第一次 get 拿 A 的结果（3s）→ 然后 B 的（已经完成，立刻返回）→ 然后 C（再等 2s）→ D 已完成 → E 已完成。

总耗时是 5s（最慢的那个）。这没问题。

但中间 3s ~ 5s 之间 D、E、B 都已经完成了，结果还在原地等 C——如果"处理结果"也耗时（比如把结果写 DB），整个流水线被最慢的任务卡住。

理想情况是：谁先完成，就先处理谁的结果——而不是按提交顺序傻等。ExecutorCompletionService 就是为这件事设计的。

一、CompletionService 是什么

CompletionService 是 JDK 5 就有的接口，但很多人不知道它存在：

1
2
3
4
5
6


public interface CompletionService<V> {
 Future<V> submit(Callable<V> task);
 Future<V> take() throws InterruptedException; // 阻塞，拿一个完成的
 Future<V> poll(); // 非阻塞
 Future<V> poll(long timeout, TimeUnit unit); // 超时
}

它内部维护一个已完成任务队列——任何任务完成后立刻进队列，take() 从队列取出一个。

flowchart LR
 Submit[submit×N] --> Pool[ThreadPool]
 Pool --> Done[已完成队列]
 Take[take/poll] -.从队列读.-> Done

先完成的先被取走——而不是按提交顺序等。

二、用法对比

反例：朴素 Future.get()

1
2
3
4
5
6
7
8
9


ExecutorService pool = Executors.newFixedThreadPool(5);
List<Future<Result>> futures = tasks.stream()
 .map(t -> pool.submit(() -> callApi(t)))
 .collect(toList());

for (Future<Result> f : futures) {
 Result r = f.get(); // 按提交顺序阻塞
 handle(r);
}

正解：CompletionService

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


ExecutorService pool = Executors.newFixedThreadPool(5);
CompletionService<Result> ecs = new ExecutorCompletionService<>(pool);

for (Task t : tasks) {
 ecs.submit(() -> callApi(t));
}

for (int i = 0; i < tasks.size(); i++) {
 Result r = ecs.take().get(); // 先完成的先返回
 handle(r);
}

唯一变化是 take() 替代了 f.get()——但行为完全不同。

三、性能差异：一个真实数字

5 个任务，耗时分别 1s、1s、2s、3s、5s。handle() 处理每个结果耗时 1s。

方案	耗时
朴素 Future.get()	5s + 5×1s = 10s （处理被串行化）
CompletionService	5s + 1s = 6s （处理跟着完成走）

任务越多、处理越重，差距越大。这是 CompletionService 的真正价值——让"等待"和"处理"重叠。

四、典型场景

1. 并发调多个外部接口聚合

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


public List<UserVO> batchGetUsers(List<Long> ids) {
 CompletionService<UserVO> ecs = new ExecutorCompletionService<>(pool);
 for (Long id : ids) {
 ecs.submit(() -> rpcGetUser(id));
 }
 List<UserVO> result = new ArrayList<>();
 for (int i = 0; i < ids.size(); i++) {
 try {
 result.add(ecs.take().get());
 } catch (Exception e) {
 log.warn("partial failure", e);
 }
 }
 return result;
}

2. 并发处理大批量数据，结果立刻入库

1
2
3
4
5
6
7
8


CompletionService<Record> ecs = new ExecutorCompletionService<>(pool);
for (Long id : ids) {
 ecs.submit(() -> heavyCompute(id));
}
for (int i = 0; i < ids.size(); i++) {
 Record r = ecs.take().get();
 repository.save(r); // 一完成就入库，不傻等
}

3. “找到第一个就返回"语义

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public Result findFirstHit(List<Source> sources) {
 CompletionService<Result> ecs = new ExecutorCompletionService<>(pool);
 List<Future<Result>> futures = sources.stream()
 .map(s -> ecs.submit(() -> tryQuery(s)))
 .collect(toList());

 try {
 for (int i = 0; i < sources.size(); i++) {
 Result r = ecs.take().get();
 if (r != null) {
 return r; // 第一个非空结果返回
 }
 }
 return null;
 } finally {
 futures.forEach(f -> f.cancel(true)); // 取消其他
 }
}

五、和 CompletableFuture 的区别

JDK 8 的 CompletableFuture 是更强大的并发工具——能不能用它替代 CompletionService？

1
2
3
4
5
6


List<CompletableFuture<Result>> futures = tasks.stream()
 .map(t -> CompletableFuture.supplyAsync(() -> callApi(t), pool))
 .collect(toList());

CompletableFuture.allOf(futures.toArray(new CompletableFuture[0]))
 .thenApply(v -> futures.stream().map(CompletableFuture::join).collect(toList()));

CompletableFuture 能做更多事——chain / combine / handle 异常 / async。但它默认是"等所有完成"或"等任意完成”，没有"按完成顺序逐个处理"的内置语义。

要做到"按完成顺序处理"，CompletableFuture 需要这样：

1
2
3
4
5


List<CompletableFuture<Result>> futures = tasks.stream()
 .map(t -> CompletableFuture.supplyAsync(() -> callApi(t), pool))
 .collect(toList());

futures.forEach(f -> f.thenAccept(r -> handle(r)));

也行——但每个 future 完成时回调在 ForkJoinPool / 自定义池里执行，handle 之间是并发的。如果 handle 本身要按顺序做（写 DB 不能并发），还是 CompletionService 更适合。

	CompletionService	CompletableFuture
按完成顺序处理	✓	△ 用回调
顺序处理 handle	✓ 主线程串行	△ 要再加锁/单线程
链式组合 / 异常处理	△	✓ 强
async/await 风格	✗	✓
学习曲线	低	中

简单的"并发任务 + 顺序处理结果"——CompletionService 更直接。复杂的并发编排——CompletableFuture。

六、踩坑提醒

1. take() 是阻塞的

主线程会卡住。如果上层有超时要求：

1
2
3
4


Future<Result> f = ecs.poll(500, TimeUnit.MILLISECONDS);
if (f == null) {
 // 超时
}

2. take() 调用次数要等于 submit 次数

少调一次会漏处理一个结果，多调一次会无限阻塞。用 for 循环的次数严格等于 submit 数。

3. 异常需要在 .get() 里 try

1
2
3
4
5
6
7
8
9


for (int i = 0; i < n; i++) {
 Future<Result> f = ecs.take();
 try {
 Result r = f.get();
 handle(r);
 } catch (ExecutionException e) {
 log.error("task failed", e.getCause());
 }
}

ExecutionException 包装了原始异常，getCause() 才是业务真正抛的异常。

4. 共享线程池的污染

1
2


CompletionService<X> ecsA = new ExecutorCompletionService<>(sharedPool);
CompletionService<Y> ecsB = new ExecutorCompletionService<>(sharedPool);

ECS 用的是底层 pool，不会把 A、B 的结果混淆——但池子被两边任务挤占。共享池容量要够。

5. cancel 后 take 可能拿到 cancelled future

如果你 cancel 了某些任务，take 可能拿到已 cancelled 的 future，调用 f.get() 会抛 CancellationException。一定要 catch。

6. JDK 内置实现内部用 LinkedBlockingQueue

队列无界——任务慢、消费慢时队列会无限增长。海量任务场景需要自己实现 ECS（用有界队列）或者限流。

七、一份生产级模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


public <T, R> List<R> parallelExecute(
 Collection<T> tasks,
 Function<T, R> action,
 ExecutorService pool,
 long timeout,
 TimeUnit unit) {

 CompletionService<R> ecs = new ExecutorCompletionService<>(pool);
 List<Future<R>> futures = tasks.stream()
 .map(t -> ecs.submit(() -> action.apply(t)))
 .collect(toList());

 long deadline = System.nanoTime() + unit.toNanos(timeout);
 List<R> results = new ArrayList<>();
 try {
 for (int i = 0; i < tasks.size(); i++) {
 long remaining = deadline - System.nanoTime();
 Future<R> f = ecs.poll(remaining, TimeUnit.NANOSECONDS);
 if (f == null) {
 log.warn("partial timeout, completed {}/{}", i, tasks.size());
 break;
 }
 try {
 results.add(f.get());
 } catch (ExecutionException e) {
 log.error("task failed", e.getCause());
 }
 }
 } catch (InterruptedException e) {
 Thread.currentThread().interrupt();
 } finally {
 futures.forEach(f -> f.cancel(true)); // 主流程结束时取消未完成任务
 }
 return results;
}

小结

把全文压一句：

ExecutorCompletionService 让『先完成的任务先被处理』——这是 Java 并发里最被低估的一个工具。

什么时候选它：

多个任务并发执行
需要按完成顺序逐个处理结果
处理逻辑本身耗时 / 串行
不需要 CompletableFuture 的复杂编排

工程纪律：

submit 几次就要 take 几次
异常 catch ExecutionException + getCause
主流程结束 cancel 未完成任务
海量任务时换有界队列实现

下次再写"并发调 N 个外部接口然后处理结果"时——别再 for 循环 f.get() 了。

服务端到客户端的进度推送：SSE 与 WebSocket 选型

Thu, 12 Mar 2020 16:00:00 +0800

一个看似简单的需求

用户在管理后台点"导出报表"——服务端要生成一个 200MB 的 Excel，前端等 30 秒。最差的体验是这样：

点了按钮，前端转圈圈。30 秒过去——用户以为卡住了，开始连点。后端被点出三次重复任务，最后崩了。

合格的体验应该是：

点了按钮，立刻看到"正在生成 Excel…12%"，每秒进度条往上跳，用户安心等待。

实现这种"实时进度反馈"看起来不复杂——但坑很多：

HTTP 是请求-响应模型，服务端没法主动告诉前端"现在 20% 了"
进度怎么从生成 Excel 的线程"流"到 HTTP 响应里
浏览器有 Range 请求、有 chunked 编码、有 SSE、有 WebSocket——该选哪个

本文把三种主流方案讲清楚——HTTP 流式响应、SSE、WebSocket。各自的优劣、代码、踩坑都覆盖。

一、需求拆解：什么叫"下载进度"

要讲清进度反馈，先把"下载"分两类：

类型 A：纯文件传输

文件已存在，浏览器直接下载——进度信息浏览器自己能算（Content-Length / 已接收字节）。前端不需要服务端告诉，可以自己监听 progress 事件。这种场景根本不需要后端反馈。

1
2
3
4
5
6
7
8


const xhr = new XMLHttpRequest();
xhr.responseType = 'blob';
xhr.onprogress = e => {
 const percent = (e.loaded / e.total * 100).toFixed(1);
 setProgress(percent); // 浏览器自己算
};
xhr.open('GET', '/file/download/1');
xhr.send();

这种是大部分场景——多数情况下不需要后端介入，避免加不必要的复杂度。

类型 B：服务端要先"做事"才有文件

真正复杂的——服务端先生成 Excel（30 秒）、再让前端下载。生成过程中浏览器看到的是 0 字节、Content-Length 还没确定。进度只有服务端知道。

类型 B 才是本文的主场。

二、方案 1：HTTP 流式响应（chunked）

最简单的姿势——把"任务进度"和"最终文件"塞到一个 HTTP 响应里。

服务端用 StreamingResponseBody，每行输出一个 JSON（NDJSON / JSON-Lines）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@GetMapping("/export")
public ResponseEntity<StreamingResponseBody> export() {
 StreamingResponseBody stream = output -> {
 for (int i = 0; i <= 100; i += 10) {
 // 输出一行 JSON + \n
 String line = String.format("{\"progress\":%d}\n", i);
 output.write(line.getBytes(StandardCharsets.UTF_8));
 output.flush();
 Thread.sleep(500); // 模拟工作
 }
 output.write("{\"done\":true,\"url\":\"/file/123\"}\n".getBytes(StandardCharsets.UTF_8));
 };
 return ResponseEntity.ok()
 .contentType(MediaType.parseMediaType("application/x-ndjson"))
 .body(stream);
}

这里故意不用 SSE 的 data: …\n\n 协议格式——避免和方案 2 混淆。要 SSE 就直接用 SseEmitter（见方案 2），这里就是普通的"按行 JSON 流"。

前端用 fetch + ReadableStream 读：

1
2
3
4
5
6
7
8


const resp = await fetch('/export');
const reader = resp.body.getReader();
while (true) {
 const { done, value } = await reader.read();
 if (done) break;
 const text = new TextDecoder().decode(value);
 // 解析进度
}

优点：

实现简单，一个接口搞定
浏览器原生支持

缺点：

进度信息和文件内容混在一个流里，前端要自己解析协议
不是标准协议，每个项目都可能不一样

适合简单场景——不推荐做复杂业务。

三、方案 2：SSE（Server-Sent Events）

SSE 是 HTML5 的标准——专门为"服务端推送给客户端"设计，比 WebSocket 简单一半。

服务端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


@GetMapping(value = "/export/stream", produces = MediaType.TEXT_EVENT_STREAM_VALUE)
public SseEmitter exportStream() {
 SseEmitter emitter = new SseEmitter(60_000L); // 60s 超时

 executor.execute(() -> {
 try {
 for (int i = 0; i <= 100; i += 5) {
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i, "msg", "处理中...")));
 Thread.sleep(500);
 }
 // 最终输出文件下载链接
 emitter.send(SseEmitter.event()
 .name("done")
 .data(Map.of("url", "/file/12345")));
 emitter.complete();
 } catch (Exception e) {
 emitter.completeWithError(e);
 }
 });
 return emitter;
}

前端

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


const evt = new EventSource('/export/stream');

evt.addEventListener('progress', e => {
 const data = JSON.parse(e.data);
 setProgress(data.percent);
});

evt.addEventListener('done', e => {
 const data = JSON.parse(e.data);
 window.location.href = data.url;
 evt.close();
});

evt.onerror = err => {
 console.error('SSE error', err);
 evt.close();
};

SSE 的特点

服务端 → 客户端单向——客户端不能用同一通道发消息
基于 HTTP——不需要握手协议升级，CDN 能转发
自动重连——网络断了浏览器自动重连
协议极简——event 名 + data 行
比 WebSocket 轻量——但功能少一半

一个常被忽视的细节

很多 PaaS / Nginx 默认 buffer 响应，SSE 推送的消息要等 buffer 满了才到前端。要在 nginx 里关闭：

1
2
3
4
5
6


location /export/ {
 proxy_pass http://backend;
 proxy_buffering off; # ★ 关键
 proxy_read_timeout 3600s;
 chunked_transfer_encoding on;
}

不开就是"明明代码 emit 了但前端 30 秒后才一次性收到所有进度"。

四、方案 3：WebSocket

最重量级的——双向通信，服务端推前端、前端发命令到服务端都行。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


@Component
public class ExportWebSocketHandler extends TextWebSocketHandler {

 @Override
 public void handleTextMessage(WebSocketSession session, TextMessage msg) throws Exception {
 // 收到前端"开始导出"指令后启动任务
 ExportRequest req = JSON.parseObject(msg.getPayload(), ExportRequest.class);
 executor.execute(() -> doExport(session, req));
 }

 private void doExport(WebSocketSession session, ExportRequest req) {
 try {
 for (int i = 0; i <= 100; i += 5) {
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "progress", "percent", i))));
 Thread.sleep(500);
 }
 session.sendMessage(new TextMessage(JSON.toJSONString(
 Map.of("type", "done", "url", "/file/123"))));
 } catch (Exception e) {
 log.error("export error", e);
 }
 }
}

适用场景：

同一连接里要前端 → 后端发指令（如取消任务、调整参数）
已经有 WebSocket 长连接复用
复杂双向交互（如客服聊天 + 文件传输）

但单纯做"进度反馈"上 WebSocket 是杀鸡用牛刀——SSE 已经够了。

五、三方案对比

	StreamingResponseBody	SSE	WebSocket
实现复杂度	极简	简单	中
协议	HTTP	HTTP（standard）	HTTP Upgrade
双向	✗	✗ 单向	✓
自动重连	✗	✓	✗（要自己写）
Nginx 兼容	△	△（要关 buffer）	△（要 upgrade 配置）
浏览器支持	✓ 全部	✓ 全部	✓ 全部
适用场景	进度+文件混合	单向进度反馈	双向交互

给一个直接的建议：

类型 A（纯文件下载）：浏览器原生 progress；类型 B（服务端做事 + 进度）：99% 用 SSE 就够。WebSocket 留给真正的双向场景。

六、生产细节

1. 进度的"真实性"

1
2
3
4


for (int i = 0; i <= 100; i += 5) {
 emit(i);
 Thread.sleep(500);
}

写成这样的进度是假进度——看着舒服但和真实工作进度无关。生产代码进度要从真实业务里取：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public void doExport(SseEmitter emitter, List<User> users) {
 int total = users.size();
 for (int i = 0; i < total; i++) {
 process(users.get(i));
 if (i % 100 == 0 || i == total - 1) { // 每 100 条推一次
 emitter.send(SseEmitter.event()
 .name("progress")
 .data(Map.of("percent", i * 100 / total)));
 }
 }
}

2. 异常处理

1

emitter.send(...); // 客户端断开会抛 IllegalStateException

客户端关页面、断网、超时——服务端继续 send 会异常。要 catch 后调 emitter.completeWithError(e)，并停止剩余工作（节省服务器资源）。

3. 资源清理

SseEmitter 是要释放的——onCompletion、onTimeout、onError 三个回调要注册：

1
2
3


emitter.onCompletion(() -> log.info("client disconnected"));
emitter.onTimeout(() -> log.warn("session timeout"));
emitter.onError(err -> log.error("session error", err));

4. 不要在 SSE 通道传文件本体

进度通道传进度元数据，文件本体走单独下载链接：

1
2


SSE 推送 → 任务完成时给一个临时下载 URL
前端拿到 URL → 触发标准下载

不要硬塞 base64 文件到 SSE，体积和性能都差。

5. 限流

SseEmitter 是长连接——大流量场景要限连接数（防止有人开 1 万个连接）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@RestController
public class ExportController {
 private final Semaphore connections = new Semaphore(100); // 最多 100 并发

 @GetMapping("/export/stream")
 public SseEmitter export() {
 if (!connections.tryAcquire()) {
 throw new BusinessException("服务繁忙");
 }
 SseEmitter emitter = new SseEmitter();
 emitter.onCompletion(connections::release);
 emitter.onTimeout(connections::release);
 emitter.onError(e -> connections.release());
 // ...
 return emitter;
 }
}

6. 跨进程任务进度

如果导出任务是异步发到 MQ 或别的进程执行——进度数据要走 Redis：

flowchart LR
 Front --> SSE[SSE Endpoint]
 SSE -.poll.-> Redis[(Redis)]
 Worker[(异步 Worker)] -.write.-> Redis

SSE 通道每秒查一次 Redis 拿进度推给前端，Worker 进度写 Redis。进度生产和消费解耦。

小结

把全文压一句：

HTTP 是请求响应模型，要做"实时进度反馈"，就要打开一个『可以持续推送』的通道——单向选 SSE，双向选 WebSocket，文件本体永远走标准 HTTP 下载。

工程要点：

浏览器原生 progress 能算的进度，别让后端反馈
后端进度反馈优先 SSE
真实进度比假进度重要
Nginx proxy_buffering off 是 SSE 必配
进度和文件本体分离

把这套方案吃透，“导出报表"这种烦人功能能瞬间从 1 星体验变成 5 星。

Spring 参数校验完整指南：JSR-380 与 Hibernate Validator

Sat, 17 Aug 2019 16:30:00 +0800

校验该写在哪一层？

很多项目里随处可见这样的代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


public Result createUser(UserDTO dto) {
 if (dto.getName() == null || dto.getName().isEmpty()) {
 return Result.fail("姓名不能为空");
 }
 if (dto.getAge() == null || dto.getAge() < 0 || dto.getAge() > 200) {
 return Result.fail("年龄不合法");
 }
 if (!Pattern.matches("^1[3-9]\\d{9}$", dto.getPhone())) {
 return Result.fail("手机号格式错误");
 }
 // ... 真正的业务逻辑
}

每个 Controller 都重复一遍，手工拼错误消息，堆得密不透风。这种代码不该出现在业务方法里——校验是输入边界的责任，应该在数据进入业务方法前就被自动拦截。

Bean Validation（JSR-380）和它的事实标准实现 Hibernate Validator 就是为这件事而生。今天我们把它的常见用法和"骚姿势"过一遍。

基础：常用注解一览

注解	作用	适用类型
`@NotNull`	不能为 null	任意
`@NotEmpty`	不能 null 且不能为空	String / Collection / Array
`@NotBlank`	不能 null 且 trim 后非空	String
`@Size(min,max)`	长度/大小范围	String / Collection
`@Min` / `@Max`	数值最小/最大	数字
`@DecimalMin/Max`	支持 BigDecimal 的最小最大	数字
`@Positive` / `@Negative`	正数 / 负数	数字
`@Pattern(regexp)`	正则匹配	String
`@Email`	邮箱格式	String
`@Past` / `@Future`	过去 / 未来时间	时间类型
`@AssertTrue`	必须为 true	boolean
`@Valid`	触发嵌套校验	对象 / 集合

一份典型的 DTO：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


public class UserCreateDTO {

 @NotBlank(message = "姓名不能为空")
 @Size(max = 20, message = "姓名最长 20 个字")
 private String name;

 @NotNull(message = "年龄必填")
 @Min(value = 0, message = "年龄不能为负")
 @Max(value = 200, message = "年龄太离谱了")
 private Integer age;

 @Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号格式不对")
 private String phone;

 @Email(message = "邮箱格式不对")
 private String email;

 @Valid // 嵌套校验
 private AddressDTO address;
}

接入 Spring：一个 `@Valid` 全自动

Spring MVC 集成是开箱即用的——参数前加 @Valid，校验失败会抛 MethodArgumentNotValidException：

1
2
3
4
5


@PostMapping("/users")
public Result createUser(@RequestBody @Valid UserCreateDTO dto) {
 // 进到这里，所有约束都已经通过
 return userService.create(dto);
}

Path Variable / Request Param 上需要 @Validated 在 Controller 类上配合：

1
2
3
4
5
6
7
8
9


@RestController
@Validated
public class UserController {

 @GetMapping("/users/{id}")
 public Result get(@PathVariable @Min(1) Long id) {
 return userService.get(id);
 }
}

Path/Param 校验失败会抛 ConstraintViolationException，异常类型和 @RequestBody 不一样，需要分别处理。

全局异常处理：让校验报错优雅返回

Controller 内部不该处理校验异常，应该用全局异常处理器统一处理：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


@RestControllerAdvice
public class GlobalExceptionHandler {

 // @RequestBody 校验失败
 @ExceptionHandler(MethodArgumentNotValidException.class)
 public Result handleBody(MethodArgumentNotValidException e) {
 String msg = e.getBindingResult().getFieldErrors().stream()
 .map(f -> f.getField() + ": " + f.getDefaultMessage())
 .collect(Collectors.joining("; "));
 return Result.fail(400, msg);
 }

 // @RequestParam / @PathVariable 校验失败
 @ExceptionHandler(ConstraintViolationException.class)
 public Result handleParam(ConstraintViolationException e) {
 String msg = e.getConstraintViolations().stream()
 .map(v -> v.getPropertyPath() + ": " + v.getMessage())
 .collect(Collectors.joining("; "));
 return Result.fail(400, msg);
 }
}

至此基础就齐了。下面才是真正出彩的"骚姿势"。

骚姿势一：分组校验（Validation Groups）

最常见的场景：新增和修改用的是同一个 DTO，但字段约束不同。新增时 id 不能传，修改时 id 必填——硬拆两个 DTO 又冗余。

分组校验解决这个问题：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


public interface CreateGroup {}
public interface UpdateGroup {}

public class UserDTO {

 @Null(message = "新增时不能传 ID", groups = CreateGroup.class)
 @NotNull(message = "修改时必须传 ID", groups = UpdateGroup.class)
 private Long id;

 @NotBlank(groups = {CreateGroup.class, UpdateGroup.class})
 private String name;
}

@PostMapping("/users")
public Result create(@RequestBody @Validated(CreateGroup.class) UserDTO dto) { ... }

@PutMapping("/users")
public Result update(@RequestBody @Validated(UpdateGroup.class) UserDTO dto) { ... }

注意——分组要用 @Validated 不能用 @Valid，因为 @Valid 不支持分组参数。

骚姿势二：嵌套校验

DTO 嵌 DTO 时，光在外层加 @Valid 是不够的，必须在内层字段上也加 @Valid，校验才会递归下去：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


public class OrderDTO {

 @NotEmpty
 @Valid // ← 关键
 private List<OrderItemDTO> items;
}

public class OrderItemDTO {
 @NotNull private Long skuId;
 @Min(1) private Integer count;
}

如果集合里有元素违规，错误路径会是 items[2].count，前端能精确定位。

骚姿势三：跨字段校验（自定义类级注解）

校验"密码和确认密码必须一致"这种字段间约束，单字段注解搞不定，需要写一个类级注解：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = PasswordMatchValidator.class)
public @interface PasswordMatch {
 String message() default "两次密码不一致";
 Class<?>[] groups() default {};
 Class<? extends Payload>[] payload() default {};
}

public class PasswordMatchValidator implements ConstraintValidator<PasswordMatch, RegisterDTO> {
 @Override
 public boolean isValid(RegisterDTO dto, ConstraintValidatorContext context) {
 if (dto.getPassword() == null) return true; // 让 @NotBlank 去管 null
 boolean match = dto.getPassword().equals(dto.getConfirmPassword());
 if (!match) {
 // 让错误"挂"在 confirmPassword 字段上而不是整个对象上
 context.disableDefaultConstraintViolation();
 context.buildConstraintViolationWithTemplate("两次密码不一致")
 .addPropertyNode("confirmPassword")
 .addConstraintViolation();
 }
 return match;
 }
}

@PasswordMatch
public class RegisterDTO {
 @NotBlank private String password;
 @NotBlank private String confirmPassword;
}

骚姿势四：自定义字段约束

校验"枚举值必须在指定集合内"是另一个常见需求。写一个 @Enum 自定义约束：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


@Target({ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
@Constraint(validatedBy = EnumValidator.class)
public @interface EnumValue {
 String message() default "值不在允许范围内";
 Class<?>[] groups() default {};
 Class<? extends Payload>[] payload() default {};

 Class<? extends Enum<?>> enumClass();
 String method() default "name"; // 用 enum 的哪个方法取值
}

public class EnumValidator implements ConstraintValidator<EnumValue, Object> {
 private Set<Object> values;

 @Override
 public void initialize(EnumValue ann) {
 values = Arrays.stream(ann.enumClass().getEnumConstants())
 .map(e -> ReflectUtil.invoke(e, ann.method()))
 .collect(Collectors.toSet());
 }
 @Override
 public boolean isValid(Object value, ConstraintValidatorContext ctx) {
 return value == null || values.contains(value);
 }
}

用法：

1
2


@EnumValue(enumClass = OrderStatus.class, method = "getCode")
private String status;

写一次，全项目复用。

骚姿势五：Service 层方法参数校验

@Validated 不只能用在 Controller，也能用在 Service：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


@Service
@Validated
public class UserService {

 public User getById(@Min(1) Long id) {
 // ...
 }

 public void batchCreate(@NotEmpty @Valid List<UserDTO> users) {
 // ...
 }
}

被 @Validated 标注的类，方法参数上的约束会通过 AOP 自动校验，失败抛 ConstraintViolationException。这意味着——业务方法可以放心地把"非法输入"假设成不可能发生。

骚姿势六：错误消息国际化

把 message 写成 {key} 形式，Hibernate Validator 会自动从 messages.properties 读取：

1
2


@NotBlank(message = "{user.name.notBlank}")
private String name;

src/main/resources/messages.properties：

1

user.name.notBlank=姓名不能为空

src/main/resources/messages_en.properties：

1

user.name.notBlank=Name is required

Spring Boot 默认就开启了国际化支持，根据请求 Accept-Language 自动切换。

骚姿势七：编程式 API 与 failFast

少数场景注解搞不定——例如根据运行时参数切换分组、或希望"遇到第一个错误就停"。可以用编程式 Validator：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


// 1. 自定义 ValidatorFactory，开启 failFast
@Bean
public Validator validator() {
 return Validation.byProvider(HibernateValidator.class)
 .configure()
 .failFast(true) // 任一字段失败立即返回，不再校验后续
 .buildValidatorFactory()
 .getValidator();
}

// 2. 编程式调用，按运行时条件选 group
@Autowired private Validator validator;

public void create(UserDTO dto, boolean strict) {
 Set<ConstraintViolation<UserDTO>> errors = strict
 ? validator.validate(dto, StrictGroup.class)
 : validator.validate(dto);
 if (!errors.isEmpty()) throw new IllegalArgumentException(...);
}

failFast 适合批量导入这种"快报快停"的场景；编程式 API 适合规则需要根据上下文动态切换。注解和编程式 API 完全可以混用——80% 用注解、20% 用 API 兜底。

一些工程上的踩坑提醒

@NotEmpty ≠ @NotBlank——前者认空白字符串为有效，后者会 trim
@Valid 和 @Validated 不要混用——分组场景必须 @Validated，嵌套校验只能 @Valid
基本类型的 @NotNull 是没用的——int、long 这些永远有默认值；要校验"必填"就得用包装类型
groups 默认值是 Default.class——不指定 groups 的注解只在不传分组时生效；你给某个注解加了 groups = Update.class，新增校验时它就不参与了
错误消息别堆业务逻辑——消息只描述"为什么不合法"，不要写"请联系管理员"这种和校验无关的话
DTO 复用别贪心——三种以上场景共用一个 DTO 时，强烈建议拆开，分组校验维护成本会爆炸

小结

Hibernate Validator 的价值不只是"少写 if"，它把输入校验从业务逻辑中剥离，让业务方法可以放心地假设"参数都是合法的"。

把今天的内容压一句：

校验是边界的责任，不是业务方法的责任。让框架帮你拦在门口，业务里只关心业务。

至于使用层级：

能用注解就用注解——分组、嵌套、自定义约束都属于注解能力
跨字段或动态规则——写自定义类级注解或编程式 API
Service 层也别放过——加 @Validated 让内部接口也享受框架保护

把这些招数都用上，Controller 里再也不会有那一行行傻乎乎的 if (xxx == null)。

Redis 分布式锁演进：六个版本的取舍与陷阱

Thu, 22 Mar 2018 19:30:00 +0800

为什么需要分布式锁

单机环境下用 synchronized 或 ReentrantLock 就能搞定的事，一旦上了微服务、跑在多台机器上，就立刻变成另一个量级的问题。

举几个最典型的场景：

下单扣库存：同一个 SKU 在多实例同时被下单，怎么保证库存不卖超？
定时任务防重：每个微服务实例都跑了定时调度，怎么让"全局只有一个执行"？
接口幂等：用户连点两次，怎么保证只处理一次？
资源独占：同一个用户、同一个文件，同时只能由一个请求修改？

进程内的锁帮不了你，因为它们彼此根本不知道对方存在。要在跨进程、跨机器的环境里"约定一个谁能进谁不能进"，就需要一个所有节点都信任的第三方——Redis 是最常见的选择。

但 Redis 分布式锁这件事，看着简单，做对极难。下面我们从最朴素的写法一路演进，把每个版本里"看似能用其实不行"的坑摊开。

姿势一：`SETNX` + `EXPIRE`（错误示范）

刚接触分布式锁的人，最常写出来的版本是这样：

1
2
3
4
5
6
7
8
9


// 反面教材
public boolean tryLock(String key, String value, long expireSeconds) {
 Long result = jedis.setnx(key, value); // 只在 key 不存在时才设置
 if (result == 1) {
 jedis.expire(key, expireSeconds); // 设置过期时间
 return true;
 }
 return false;
}

逻辑看起来很自然——抢到了就设过期时间防止死锁。但这里藏着一个致命缺陷：

SETNX 和 EXPIRE 是两条命令，不是原子操作。

如果在 SETNX 成功之后、EXPIRE 之前进程崩了、网络抖了、Redis 主从切换了，那这把锁就永远没有过期时间——所有后续请求都会被它挡住，直到运维手动删 key。

姿势二：`SET key value NX EX` 一条命令搞定

Redis 2.6.12 之后，SET 命令支持了原子的 NX + EX 选项，这就是真正可用的"上锁"操作：

1
2
3
4


public boolean tryLock(String key, String value, long expireSeconds) {
 String result = jedis.set(key, value, "NX", "EX", expireSeconds);
 return "OK".equals(result);
}

NX 保证只在 key 不存在时才生效，EX 同时设置过期时间，整个操作是原子的，没有了"SETNX 后 EXPIRE 前"那个空窗。

但这只是把"上锁"做对了，“解锁"还藏着一个更隐蔽的坑。

姿势三：解锁的"误删别人锁"问题

一个看似无害的解锁实现：

1
2
3
4


// 反面教材
public void unlock(String key) {
 jedis.del(key);
}

设想一个时序：

时刻	客户端 A	客户端 B
t1	加锁成功，过期时间 10s
t2	业务执行卡住了 12s（GC、网络等）
t3		锁已过期，B 加锁成功
t4	A 醒来，调用 unlock 直接 DEL
t5		B 还在执行，锁却没了

A 删掉了 B 的锁。后续的 C 又能进来，锁的互斥语义彻底失效。

正确做法：解锁前先验证 value

加锁时把 value 设成一个唯一标识（比如 UUID），解锁时验证 value 是自己的才删：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


String requestId = UUID.randomUUID().toString();
jedis.set(key, requestId, "NX", "EX", 10);

// 解锁
String script =
 "if redis.call('get', KEYS[1]) == ARGV[1] then " +
 " return redis.call('del', KEYS[1]) " +
 "else " +
 " return 0 " +
 "end";
jedis.eval(script, Collections.singletonList(key), Collections.singletonList(requestId));

注意：判断 + 删除必须用 Lua 脚本保证原子性。如果分两步——先 GET 再 DEL，又会回到"判断后 DEL 前锁过期了"的老问题。

姿势四：业务执行时间不可控——锁自动续期（看门狗）

即便解锁做对了，“业务执行时间超过锁过期时间"本身就是个隐患。永远把过期时间设很长？万一这个客户端进程真的死了，锁就长时间得不到释放。

更优雅的做法是自动续期：客户端在持有锁期间，启动一个后台线程定时把锁的过期时间往后顺。

伪代码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 上锁成功后，启动一个守护线程
ScheduledExecutorService watchdog = Executors.newSingleThreadScheduledExecutor();
watchdog.scheduleAtFixedRate(() -> {
 // 每 expireSeconds/3 触发一次续期
 String script =
 "if redis.call('get', KEYS[1]) == ARGV[1] then " +
 " return redis.call('expire', KEYS[1], ARGV[2]) " +
 "else return 0 end";
 jedis.eval(script, ..., requestId, expireSeconds);
}, expireSeconds / 3, expireSeconds / 3, TimeUnit.SECONDS);

业务结束后停掉 watchdog 并解锁。

这套机制如果自己手写很容易出错，所以——绝大多数生产项目直接用 Redisson。

姿势五：Redisson——工业级实现

Redisson 是 Redis 的 Java 客户端，把分布式锁封装得相当成熟，自带可重入、自动续期、公平锁、读写锁等高级特性。

1
2
3
4
5
6
7
8
9


RedissonClient redisson = Redisson.create(config);
RLock lock = redisson.getLock("order:1001");

try {
 lock.lock(); // 默认 30s 过期，看门狗每 10s 自动续期一次
 // 业务逻辑
} finally {
 lock.unlock();
}

Redisson 内部干了什么：

加锁用 Lua 脚本，原子完成"判断 + 设置 + 续期间隔记录”
可重入通过 Hash 结构记录"持有者 + 重入次数”
看门狗每 1/3 过期时间触发一次续期，业务不结束锁不释放
解锁也用 Lua 脚本，安全地把重入计数减一直到删除

业务侧能做到"加锁就像 synchronized 一样自然"，这正是它的价值。

⚠️ 看门狗的关键陷阱：看门狗只在你不显式指定 leaseTime 时才会启用——也就是 lock.lock() / lock.lock(-1, ...) / tryLock(waitTime, unit)。一旦你调用 lock(leaseTime, unit) 或 tryLock(waitTime, leaseTime, unit) 显式传了 leaseTime，看门狗会被关闭，锁到期后直接释放，不再续期。这是初学者最容易踩的坑——看着代码"用了 Redisson 应该有看门狗"，实际锁早就过期了。

姿势六：Redlock 与"红锁争议"

前面所有方案都建立在一个假设上——Redis 单机或主从是可靠的。但现实中有两个隐患：

单机 Redis 是单点，挂了所有锁都丢
Redis 主从有异步复制延迟。主刚加完锁还没复制到从，主挂了，从被选为新主，新主上没有这把锁——新的客户端就能再加一次

Redis 作者 antirez 为此提出了 Redlock 算法：

部署 N 个互相独立的 Redis 实例（比如 5 个），客户端尝试在这 N 个实例上依次加锁。只有在 大多数实例（≥ N/2 + 1） 都加锁成功，且总耗时小于锁过期时间，才认为加锁成功。

sequenceDiagram
 Client->>Redis-1: SET NX EX
 Client->>Redis-2: SET NX EX
 Client->>Redis-3: SET NX EX
 Client->>Redis-4: SET NX EX
 Client->>Redis-5: SET NX EX
 Note over Client: 至少 3/5 成功才算获得锁
 Note over Client: 释放时向所有节点发 DEL

Redisson 也实现了 Redlock：RedissonRedLock。

Martin Kleppmann 的反驳

不过 Redlock 在学界一直有争议。著名分布式系统专家 Martin Kleppmann 写过一篇 “How to do distributed locking”，指出 Redlock 在以下场景下并不安全：

客户端 GC 暂停——加锁后业务卡了几秒，锁早过期了，业务以为自己还持有锁继续操作
时钟漂移——节点之间的系统时钟不一致，过期时间判断会失准

他的结论是：对正确性要求极高的场景，应该用 ZooKeeper / etcd 这类基于一致性协议的系统；Redis 锁更适合"性能优先、偶尔失误可接受"的场景。

工程上多数业务场景用 Redisson 单实例锁就足够——性能高、用法简单；只有对正确性极敏感的少数场景才上 ZooKeeper。

各姿势对比

姿势	安全性	复杂度	推荐度
`SETNX` + `EXPIRE`	✗	低	别用
`SET NX EX`	△	低	学习用，生产不够
加 value 校验解锁	◯	中	自己造轮子的最低底线
加 Watchdog 续期	◯	高	自己造轮子的上限
Redisson 单实例	◯	低	绝大多数业务的最佳选择
Redlock / RedissonRed	◯+	中	可用但有争议，慎用
ZooKeeper / etcd 锁	✓	中高	强一致性要求场景

实战中的几条建议

永远用 tryLock 带超时，不要 lock() 死等
加锁粒度尽量细——别把整个订单创建过程锁起来，只锁库存扣减那一段
业务和锁解耦——业务方法里只关心 lock.tryLock() / lock.unlock()，不要散落 Redis 命令
过期时间 ≥ 业务最长执行时间 × 2，给极端情况留缓冲，再配合 watchdog
解锁放 finally——别让一段异常跳过解锁
日志里打出 requestId——锁出问题排查链路全靠它

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


// 生产推荐写法（依赖看门狗自动续期 → 不传 leaseTime）
RLock lock = redisson.getLock("stock:" + skuId);
boolean locked = false;
try {
 // 等 3 秒；获取后由看门狗每 10 秒续期一次，业务不结束锁不释放
 locked = lock.tryLock(3, TimeUnit.SECONDS);
 if (!locked) {
 throw new BusinessException("操作过于频繁，请稍后再试");
 }
 // 业务逻辑
} finally {
 if (locked && lock.isHeldByCurrentThread()) {
 lock.unlock();
 }
}

isHeldByCurrentThread() 这个判断很重要——避免在某些异常路径下解了不属于自己的锁。

如果你确实需要"超时强制释放"作为兜底（防止业务永远卡死把锁吃住），就显式传 leaseTime：lock.tryLock(3, 30, TimeUnit.SECONDS)。但要清楚这种写法没有看门狗——leaseTime 必须 ≥ 业务最长执行时间 × 2，否则中途锁掉的风险会回来。

小结

Redis 分布式锁这件事，入门一行代码，做对几十行细节。

把这条演进路径压缩成一句话：

从 SETNX 到 Redisson，每一步演进都是在堵一个『看似能用其实不行』的坑。

工程上的选择反而很简单：

新项目：直接上 Redisson，别造轮子
极致正确性：上 ZooKeeper / etcd
学习理解原理：把上面六种姿势从头写一遍

理解了这些演进，下次再有人问你"Redis 锁怎么用"，你就不会只回一句 SET NX EX 了——你会先反问：“你的业务能容忍偶尔失效吗？锁持有时间可控吗？需要可重入吗？”

理解 Java SPI：JDBC、SLF4J、Spring Boot 背后的机制

Tue, 22 Aug 2017 15:30:00 +0800

一个看似平淡的问题

写过 Java 的人都用过 JDBC：

1
2


Class.forName("com.mysql.cj.jdbc.Driver"); // 早期写法
Connection conn = DriverManager.getConnection(url);

但不少人没想过——DriverManager 怎么知道要去加载 MySQL 的驱动？ 它代码里又没写 import com.mysql...。

你换成 PostgreSQL 时，只要 pom 里依赖换一下，DriverManager 就自动识别了 PG 的驱动——没改一行 Java 代码。

这背后的机制叫 SPI（Service Provider Interface）。它是 JDK 留给框架开发者的"扩展点"，让框架定义接口、第三方提供实现、运行时自动发现并加载。

理解 SPI 是看懂 JDBC、Servlet、SLF4J、Spring Boot 自动装配、Dubbo 等所有"自动加载实现"框架的钥匙。

一、SPI 在做什么

API 与 SPI 的对比：

	API（Application Programming Interface）	SPI（Service Provider Interface）
调用方向	应用调框架	框架调应用
谁定义接口	框架	框架
谁实现接口	框架	应用 / 第三方
例子	Math.max() / List.add()	JDBC Driver / SLF4J Logger 实现 / 编解码器

最简洁的理解：API 是『你调我』，SPI 是『我调你』。

二、JDK 原生 SPI：ServiceLoader

JDK 提供的最朴素 SPI 工具——java.util.ServiceLoader。三步：

1. 框架定义接口

1
2
3
4
5


package org.example.payment;
public interface PaymentChannel {
 String getName();
 boolean charge(String userId, BigDecimal amount);
}

2. 应用/第三方写实现

1
2
3
4
5


package com.alipay.spi;
public class AlipayChannel implements PaymentChannel {
 @Override public String getName() { return "alipay"; }
 @Override public boolean charge(String u, BigDecimal a) { ... }
}

3. 在 META-INF/services 下声明

文件名：META-INF/services/org.example.payment.PaymentChannel

文件内容：

1
2


com.alipay.spi.AlipayChannel
com.wechat.spi.WechatChannel

框架加载所有实现

1
2
3
4


ServiceLoader<PaymentChannel> loader = ServiceLoader.load(PaymentChannel.class);
for (PaymentChannel c : loader) {
 System.out.println("found: " + c.getName());
}

只要 classpath 里有对应实现的 jar，就自动被发现——这就是 JDBC 不需要写 Class.forName 也能加载驱动的秘密。

三、JDBC 4.0 后的 SPI 实践

JDBC 4.0 之前，每次都要 Class.forName("com.mysql.jdbc.Driver")——靠类初始化触发驱动注册：

1
2
3
4


// MySQL Driver 类内部
static {
 DriverManager.registerDriver(new Driver());
}

JDBC 4.0 之后，MySQL 驱动 jar 里加了：

1
2


META-INF/services/java.sql.Driver
└─ com.mysql.cj.jdbc.Driver

DriverManager 启动时用 ServiceLoader 自动找所有 Driver 实现，Class.forName 这行代码就成了历史遗物。

四、ServiceLoader 的几个限制

1. 加载所有实现，不能选择性加载

ServiceLoader.load() 会实例化所有实现——10 个支付通道都用不上你只想要支付宝？没办法，全部都会被 new 出来。

2. 实现必须有无参构造器

1
2


public AlipayChannel(String appId) { ... } // ❌ 不行
public AlipayChannel() { ... } // ✓

需要参数？只能后续 setter 注入。

3. 没有"按 key 取实现"的能力

业务里通常是"知道用户选了 alipay，加载支付宝实现"。ServiceLoader 只能一股脑把所有实现都返回，再让你自己按 getName() 过滤。

4. 不支持 IoC 注入

实现里如果想 @Autowired 其他 Bean？不行——ServiceLoader 不知道 Spring 容器存在。

5. 类加载器问题

线程上下文 ClassLoader 是个老大难——容器化部署、OSGi 等场景下 ServiceLoader.load() 看不到某些 jar 的实现。

五、Dubbo SPI：JDK SPI 的强化版

Dubbo 团队觉得 JDK SPI 不够用，自己写了一套 SPI——位置一样在 META-INF/services / META-INF/dubbo 下，但能力翻倍。

文件格式：`key = 实现类`

1
2
3
4


# META-INF/dubbo/org.apache.dubbo.rpc.Protocol
dubbo = org.apache.dubbo.rpc.protocol.dubbo.DubboProtocol
http = org.apache.dubbo.rpc.protocol.http.HttpProtocol
hessian = org.apache.dubbo.rpc.protocol.hessian.HessianProtocol

按 key 取实现

1
2


ExtensionLoader<Protocol> loader = ExtensionLoader.getExtensionLoader(Protocol.class);
Protocol dubbo = loader.getExtension("dubbo"); // ★ 按 key 加载

不需要把所有实现都 new 一遍。

自适应扩展（Adaptive）

最强大的特性——根据运行时 URL 参数自动选择实现：

1
2
3
4
5


@Adaptive
public interface Protocol {
 Exporter export(Invoker invoker) throws RpcException;
 Invoker refer(Class type, URL url);
}

调用时根据 url.protocol 决定具体走哪个实现，业务代码完全不感知。这是 Dubbo 路由、协议适配、序列化适配等很多机制的底座。

依赖注入

Dubbo SPI 加载实现时会自动注入它依赖的其他 SPI 实现——有简化版 IoC：

1
2
3
4


public class DubboProtocol implements Protocol {
 private Codec codec; // 自动按类型注入
 public void setCodec(Codec codec) { this.codec = codec; }
}

IOC + AOP

加上 Wrapper 机制，能在所有实现外包一层"拦截器"——这就是 Dubbo 链式 Filter 的原理。

	JDK SPI	Dubbo SPI
按 key 加载	✗	✓
懒加载实现	✗	✓
依赖注入	✗	✓
AOP 包装	✗	✓
自适应扩展	✗	✓

六、Spring Factories：Spring 自己的 SPI

Spring Boot 也实现了类似的 SPI——spring.factories：

1
2
3
4
5
6


# META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
 com.example.MyAutoConfiguration

org.springframework.boot.env.EnvironmentPostProcessor=\
 com.example.MyEnvProcessor

Spring Boot 启动时会扫描所有 jar 的 spring.factories，按 key 加载对应类——这就是 starter 自动装配的本质。

Spring Boot 2.7 后逐步迁移到 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports，理由是按"接口名 = 文件名"的方式更清晰。

总结这几套 SPI 的演进：

flowchart LR
 JDK["JDK ServiceLoader
(全加载, 无 key)"]
 Spring["Spring Factories
(按 key 配置)"]
 Dubbo["Dubbo SPI
(IoC + AOP + 自适应)"]

 JDK --> Spring --> Dubbo

七、写一个自己的 SPI 框架（极简版）

理解 SPI 最快的方式是自己写一个。来个最小可工作版本：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


public class MySpi {
 private static final Map<Class<?>, Map<String, Object>> CACHE = new HashMap<>();

 public static <T> T load(Class<T> type, String name) {
 Map<String, Object> map = CACHE.computeIfAbsent(type, MySpi::loadAll);
 return (T) map.get(name);
 }

 private static Map<String, Object> loadAll(Class<?> type) {
 Map<String, Object> map = new HashMap<>();
 try {
 String path = "META-INF/myspi/" + type.getName();
 Enumeration<URL> urls = MySpi.class.getClassLoader().getResources(path);
 while (urls.hasMoreElements()) {
 try (BufferedReader br = new BufferedReader(
 new InputStreamReader(urls.nextElement().openStream()))) {
 String line;
 while ((line = br.readLine()) != null) {
 // 格式：key=class
 String[] kv = line.split("=", 2);
 Class<?> impl = Class.forName(kv[1].trim());
 map.put(kv[0].trim(), impl.getDeclaredConstructor().newInstance());
 }
 }
 }
 } catch (Exception e) {
 throw new RuntimeException(e);
 }
 return map;
 }
}

使用：

1
2
3


# META-INF/myspi/org.example.PaymentChannel
alipay = com.alipay.AlipayChannel
wechat = com.wechat.WechatChannel

1
2


PaymentChannel c = MySpi.load(PaymentChannel.class, "alipay");
c.charge(...);

加上"懒加载 + IoC + AOP"就是 Dubbo 那一套——核心思想都是"配置文件声明 + ClassLoader 加载"。

八、SPI 的常见踩坑

1. 文件路径写错

META-INF/services/全限定接口名——文件名要完整包名，不是简单名字。少一个 org.example. 就什么都加载不到。

2. 文件 BOM

UTF-8 with BOM 在某些 JDK 版本里会被读成"乱码包名"。用纯 UTF-8 不带 BOM 保存。

3. 实现类必须 public 无参构造器

AbstractXxxFactory 这种抽象类、private 构造器、没有无参构造器都加载失败。

4. 类加载器隔离

容器化部署时，框架代码可能用不同的 ClassLoader——ServiceLoader.load(Class) 默认用调用线程的 ContextClassLoader，复杂场景要显式指定。

5. SPI 失败静默

ServiceLoader 加载失败默认抛出 ServiceConfigurationError，但异常往往被框架吞了。生产排查时需要打开 SPI 加载的 DEBUG 日志。

九、什么场景该自己用 SPI

不要为了"看起来高级"而用 SPI——只有真正需要"框架代码不知道实现，但运行时能加载"时才值得：

✅ 适合 SPI 的场景：

写一个插件式框架——核心库定义接口，第三方提供实现
写一个SDK——支持多种序列化、多种存储后端
写一个多通道适配器——支付、消息推送、对象存储

❌ 不适合 SPI 的场景：

业务逻辑分发——直接用 Map<String, Strategy> 注入更清晰
简单的策略模式——枚举 + 工厂方法更简单
编译时已知所有实现——用接口注入就够了

记住一条："SPI 是给框架开发者的工具"——业务开发用 Spring 的 Map<String, T> 注入或者一个普通工厂类就够了。

小结

把全文压一句：

SPI 把"框架 → 实现"的依赖反转过来——框架定义接口，运行时由配置文件决定加载哪些实现。

理解 SPI 的几个层次：

JDK ServiceLoader：最朴素，全加载
Spring Factories：按 key 配置，能自动装配
Dubbo SPI：加上 IoC、AOP、自适应——可扩展性的天花板

工程上记住：

写框架/SDK 时考虑 SPI
业务里别滥用，简单策略用 Map 注入更清爽
文件路径、命名、字符编码三个坑特别多

把 SPI 看懂，你看 JDBC、Servlet、SLF4J、Spring Boot 自动装配的底层原理时会突然有种『原来都是这一套』的顿悟感。

关联用 ID 还是 CODE：数据库主键与外键设计实践

Wed, 15 Mar 2017 15:00:00 +0800

一个常被反复争论的设计问题

每个数据库表都有一个自增 id 主键——这件事几乎没人会争。但外键到底应该引用 id 还是引用业务编码（code），争论从未停止。

举个最常见的例子：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


-- 方案 A：用 ID 关联
CREATE TABLE orders (
 id BIGINT PRIMARY KEY,
 status_id BIGINT, -- 关联 order_status.id
 ...
);

-- 方案 B：用 CODE 关联
CREATE TABLE orders (
 id BIGINT PRIMARY KEY,
 status_code VARCHAR(32), -- 关联 order_status.code
 ...
);

注：示例里用 orders 而不是 order——order 是 SQL 保留字，直接拿来当表名要么报语法错误，要么必须加反引号 `order`。

哪种好？两派都各有铁粉，争论起来谁也说服不了谁。本文把两种方案的优劣、适用边界、工程取舍讲清楚——不给标准答案，但讲清楚什么场景该选什么。

第一原则：先区分两类外键

讨论这个问题前必须先把"外键"分成两大类——它们的处理逻辑完全不同：

关联类外键：链接两个业务实体。例如 order.user_id 指向 user.id、order_item.product_id 指向 product.id
枚举类外键：链接到字典/枚举。例如 order.status 表示订单状态、user.gender 表示性别

flowchart LR
 O1[order] -->|user_id| User[user]
 O1 -->|status_code| Dict[order_status
字典]
 O2[order_item] -->|product_id| Product[product]

关联类外键和枚举类外键，结论不一样。下面分开讲。

一、关联类外键：建议用 ID

order.user_id 这种"指向另一个业务实体"的外键，强烈建议用 ID 关联——也就是数据库自增主键或雪花 ID。

为什么用 ID

1. ID 是不变的，业务编码可能变

user_no = "U20170315001" 这种"业务用户编号"看起来像永久标识，但业务发起人随时可能要求改格式：

“把所有用户编号前缀从 U 改成 A，因为合并了 A 公司的系统。”

如果 100 张表都用 user_no 关联，改一次格式要重写 100 张表的引用——可能涉及上亿行数据。如果用 ID，业务编码爱怎么变怎么变。

2. 数字索引比字符串索引快

数据库的 B+ Tree 索引中，整数 8 字节、字符串 32 字节起步。整数索引的 IO 和比较都快得多——尤其在 join 大量数据时差距明显。

1
2
3
4
5


-- 整数 join
WHERE order.user_id = user.id

-- 字符串 join
WHERE order.user_no = user.user_no

千万级数据下，前者比后者快 30%-50% 不是稀奇事。

3. ID 是单调递增的，写入友好

InnoDB 是按主键聚簇存储的——递增 ID 写入时永远是 append，热点页只有一个。如果用业务编码（不一定单调），写入时容易引发页分裂，影响写性能。

4. 不暴露业务信息

ID 是个"无意义数字"，不会泄漏业务规模。order.id = 9876543 攻击者拿到也猜不出实际订单量；但 order.order_no = "ORD-20170315-00001" 一看就知道当天第几单。

但 ID 也不是完美

1. 跨库迁移痛

ID 是数据库自增，两个库的数据合并时 ID 必然冲突——常见做法是用雪花 ID 或一开始就用 UUID。

2. 读起来不友好

日志里看到 user_id=12345 你要去查另一张表才知道是谁。所以业务对外的 API 通常还是返回 user_no——内部 ID + 外部 code 双轨制。

二、枚举类外键：建议用 CODE

订单状态、性别、城市编码这种"指向字典"的外键，反过来——建议用 CODE 关联。

为什么用 CODE

1. 可读性极强

1
2
3
4


-- 用 ID
SELECT * FROM order WHERE status_id = 3;
-- 用 CODE
SELECT * FROM order WHERE status_code = 'PAID';

不用 join 字典表都能看懂"已支付"。线上排查问题时这个差别非常大。

2. 字典基本不会改

order_status 这种字典——PAID、SHIPPED、COMPLETED——一旦确定，几乎不会变（业务有变化也是新增，不是修改）。code 不会改的前提下，ID 的"不变性优势"就消失了。

3. 跨系统一致

字典经常要给前端、第三方对接、数据导出。PAID 比 3 通用得多——前端不用维护"3=已支付"的对照表，直接看 code 写逻辑。

4. 代码层面更清爽

业务代码用枚举 + 字符串 code 是天然契合：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


public enum OrderStatus {
 UNPAID("UNPAID"),
 PAID("PAID"),
 SHIPPED("SHIPPED"),
 COMPLETED("COMPLETED");

 private final String code;
 OrderStatus(String code) { this.code = code; }
}

// SQL 里直接 status_code = 'PAID'
// Java 里 status == OrderStatus.PAID
// 前端直接 status === 'PAID'

如果用 ID，代码里到处是 status_id == 3 这种魔法数字，可读性差，加新状态时容易和已有 ID 撞。

5. 字典表本身也得有

国内项目还有种做法是根本不建字典表，code 直接写在代码枚举里。这有它的优势——一致性强、没有"代码和数据库不同步"的问题，但缺点是修改要发版，前端没法动态拉取选项。

工程上常见做法：

简单字典直接代码枚举
需要后台管理、能配置的字典建表（status_code 作为 PK 或唯一索引）

三、混用：一种实用模式

很多项目其实是混用——业务实体用 ID 关联，枚举用 code：

1
2
3
4
5
6
7


CREATE TABLE orders (
 id BIGINT PRIMARY KEY,
 order_no VARCHAR(32) UNIQUE, -- 业务编号，对外用
 user_id BIGINT, -- 关联 user.id（关联类）
 status_code VARCHAR(32), -- 关联 order_status.code（枚举类）
 ...
);

这是一种"按字段类型选方案"的混合姿势，比"全 ID"或"全 CODE"都更贴合实际。

四、第三种争论：UUID / 雪花 ID

Long 自增 ID 适合单库，分布式场景常被替换为 UUID 或雪花 ID。

方案	优点	缺点
自增 ID	紧凑、有序、写入友好	单库限制、跨库迁移痛
UUID	全局唯一、无中心化	二进制 16 字节 / 文本 36 字符、v4 无序、写入页分裂、读取慢
雪花 ID	紧凑（Long）、有序、分布式	时钟回拨问题、需要部署机器号

关联类外键用什么主键，CODE 关联问题不大。但用 UUID 时务必走 BINARY(16) 存储而不是 CHAR(36)——前者只占一半空间且索引性能高得多（不止一倍）。

五、外键约束：要不要加 FK constraint

讨论"用 ID 还是 CODE"时，常常顺带聊另一个问题——要不要在数据库层面建外键约束：

1

ALTER TABLE order ADD CONSTRAINT fk_user FOREIGN KEY (user_id) REFERENCES user(id);

国内绝大多数生产项目不建外键约束，原因：

性能影响：每次写入都要校验外键，高并发下是负担
分库分表后约束失效：跨库 FK 是不可能的
运维痛点：表的清理、备份、迁移都被外键卡住

业内主流做法是——逻辑外键（应用层保证一致性，数据库不强制）。这意味着：

表设计上仍然要有"外键"概念
命名规范要清晰：user_id / product_id 这种命名让人一眼看出关联
数据一致性靠应用代码 + 单测覆盖

六、实战建议

flowchart TD
 Start([这个外键关联什么?])
 Start --> Type{业务实体 or 枚举字典?}
 Type -->|业务实体| ID[用 ID 关联
同时保留 业务编码 字段对外]
 Type -->|枚举字典| CHANGE{字典变化频率?}
 CHANGE -->|几乎不变| CODE[用 CODE，不依赖字典表]
 CHANGE -->|偶尔会改| BOTH[code 关联，但字典建表持久化]

具体几条建议：

业务实体外键用 ID——user_id、product_id、order_id
枚举/字典外键用 CODE——status_code、type_code
xxx_no / xxx_code 字段建唯一索引——业务上对外暴露但 DB 关联用 ID
生产环境基本都不加 FK 约束——逻辑外键 + 应用层校验
不要把"自增 ID"暴露给前端——容易暴露业务规模 + 不好做加密短链
跨库场景上雪花 ID 不要 UUID——写入性能差距很大

七、一些反例

反例 1：`user_no` 当外键

某项目用 U20170315001 这种用户编号当所有外键。三年后业务并购，要把所有 U 开头的用户改成 A 开头——全表 update + 全部关联表 update，停服 12 小时。

教训：业务编号永远可能改格式。

反例 2：状态用 ID

订单状态字典表里 1=未付款、2=已付款、3=已发货。某天产品提需求：“把’已付款’拆成’部分付款’和’全额付款’"。开发以为只要在字典加一条，结果全代码搜 status_id == 2 漏改了三处——线上有"全额付款的订单被识别为部分付款”。

教训：枚举用数字 ID 容易让代码里有魔法数字。

反例 3：用业务编码当主键

order_no 设为 order 表的主键——单字段、有序、看似优雅。但：

VARCHAR 主键聚簇索引大、IO 多
业务编码格式偶尔要改（前缀、长度）→ 主键变化引发整表 rebuild
子表关联用 VARCHAR(32) 占空间多

教训：主键应当稳定、无意义、紧凑——bigint id 是最佳形态。

小结

把全文压一句：

业务实体之间用 ID 关联，枚举字典之间用 CODE 关联——稳定的东西用稳定的标识，可读的东西用可读的标识。

记住几条工程铁律：

ID 主键永不暴露给业务规则
业务编码做唯一索引但不做外键
枚举字典 code 全大写下划线，永不复用
生产环境逻辑外键 + 应用层校验
代码里别留魔法数字，永远用枚举 + code 比较

把这几条吃透，数据库设计这层基本不会出大问题。

架构设计 on 牛哥聊技术

PancakeSwap V3 深度解析（下）：合约篇

前言

一、项目结构

二、合约层次架构

三、与 Uniswap V3 合约的实质差异

3.1 PancakeV3Pool 内部多了 LMPool hook

3.2 多了 PancakeV3LmPool 合约

3.3 MasterChefV3 vs UniswapV3Staker

3.4 FarmBooster + veCAKE 集成

3.5 费率档位常量

3.6 命名 / 前缀差异（仅 rename）

四、核心合约详解

4.1 Factory + PoolDeployer：为什么要拆成两个？

4.2 PancakeV3Pool：核心数据结构

Tick 是什么？为什么用 sqrt(price)？

4.3 NonfungiblePositionManager：NFT 化的仓位管理

五、核心流程时序

5.1 创建池

5.2 添加流动性（Mint）

5.3 交换（Swap）—— 最核心的路径

一个具体例子：跨 tick 是怎么发生的？

跨 tick 的 gas 代价

5.4 流动性挖矿（MasterChef V3）

六、聚合仓位设计：V3 的精髓

一个具体例子

为什么这么设计？

七、关键设计模式

关于 Oracle 累加器多说一句

八、踩坑提醒 / 常见误区

九、数据流总结

十、附录：数学速查

结语

PancakeSwap V3 深度解析（上）：协议篇

写在前面

一、V2 的局限：资金被"摊薄"

二、V3 的核心：集中流动性

三、Tick 与费率档位

四、NFT 仓位：每个仓位是独立 NFT

五、费用结算

六、跨多个 tick 的 swap

七、TWAP：时间加权平均价

八、做市策略

1. 被动 LP

2. 紧仓位 + 频繁调整

3. JIT（Just-In-Time）流动性

4. 范围订单（Range Orders）

5. PancakeSwap 特有：质押 NFT 进 MasterChefV3 挖 CAKE

九、PancakeSwap 协议层特有：原生挖矿与 FarmBooster

原生挖矿 vs 外挂 Staker

FarmBooster：veCAKE 的 1x ~ 2x 加权

奖励结算复用 V3 的同构机制

十、V3 仓位管理生态

十一、PancakeSwap V3 的真实数字

十二、对开发者的启发

小结

逻辑主键还是业务主键？数据库主键设计的取舍与最佳实践

写在前面

一、概念先分清：逻辑主键 vs 业务主键

逻辑主键

业务主键

二、五种主流方案

方案 1：自增 BIGINT 逻辑主键（推荐默认）

方案 2：UUID

方案 3：UUID v7（时间有序 UUID）

方案 4：雪花 ID（Snowflake）

方案 5：业务键作主键（不推荐）

三、决策树

四、生产级雪花 ID 的实现要点

1. 时钟回拨

2. 机器 ID 分配

3. 数据中心 ID

4. 序列号回滚

5. 实战推荐

五、对外暴露的"业务编码"

六、几个常见反模式

反模式 1：业务编码当主键 + 加 _old 字段做迁移

反模式 2：UUID 用 char(36)

反模式 3：自增 ID 暴露给前端

反模式 4：复合主键

反模式 1：业务编码当主键 + 加 `_old` 字段做迁移