安全防护 on 牛哥聊技术

OpenZeppelin Contracts 5.0 的关键变化

Thu, 07 Aug 2025 15:30:00 +0800

写在前面

OpenZeppelin Contracts 是 Solidity 生态最广泛使用的标准库——ERC-20、ERC-721、AccessControl、Proxy、Pausable…… 几乎每个生产级合约项目都依赖它。

2023 年 10 月发布的 5.0 是它自 4.0 之后最大的一次主版本升级——不只是 bug 修复，而是对 API、安全模型、模块组织的全面重塑。

本文讲清楚 5.0 的核心变化、升级要踩的坑、新特性的工程价值。

一、最大变化：Solidity 0.8.20+ 基线

OpenZeppelin 5.0 要求 Solidity ^0.8.20——意味着几个旧版本必须放弃：

pragma solidity ^0.8.0 不够了
升级编译器同时要校对每个 mixin/inherit

升 Solidity 版本通常是个连锁反应——所有依赖的第三方库也要兼容。

二、Ownable 必须传 `initialOwner`

最容易踩的小坑——Ownable 构造函数变了：

1
2
3
4
5
6
7
8
9


// 4.x
contract MyContract is Ownable {
 constructor() {} // 自动用 msg.sender 作为 owner
}

// 5.x
contract MyContract is Ownable {
 constructor(address initialOwner) Ownable(initialOwner) {} // 必须显式传
}

为什么改？——因为 msg.sender 在 deployer 用 factory 模式时往往不是真实的 owner。强制显式传 owner，**避免"工厂部署却把 owner 设成工厂"**这类隐蔽 bug。

升级时所有 Ownable 的子合约构造函数都要改。

三、AccessControl 的角色管理变了

`_grantRole` 移到 internal

1
2
3
4
5


// 4.x：_setupRole 用于初始化阶段
_setupRole(DEFAULT_ADMIN_ROLE, msg.sender);

// 5.x：_setupRole 删除，统一用 _grantRole
_grantRole(DEFAULT_ADMIN_ROLE, msg.sender);

_setupRole 这个"专门为初始化用"的函数被合并——减少 API 表面。

`hasRole` 行为不变，但 `getRoleMemberCount` / `getRoleMember` 移到了 `AccessControlEnumerable`

如果你需要枚举角色成员，必须显式继承 AccessControlEnumerable。

四、ERC20 的 `_beforeTokenTransfer` / `_afterTokenTransfer` 删除

4.x 钩子模型：

1
2
3
4


function _beforeTokenTransfer(address from, address to, uint256 amount) internal virtual override {
 // ...
 super._beforeTokenTransfer(from, to, amount);
}

5.x 简化为单个 _update 钩子：

1
2
3
4


function _update(address from, address to, uint256 value) internal virtual override {
 super._update(from, to, value);
 // 在这里加自定义逻辑
}

为什么改——钩子分前后两个增加了心智负担和 Gas 开销，单个 _update 函数已经覆盖所有需求。

升级时所有自定义 ERC20 / ERC721 都要把 hook 重写。

五、SafeERC20 的简化

1
2
3
4
5
6
7


// 4.x
SafeERC20.safeTransfer(token, to, amount);
SafeERC20.safeApprove(token, spender, amount); // ⚠️ 已弃用

// 5.x
token.safeTransfer(to, amount); // 用 using for
token.forceApprove(spender, amount); // 替代 safeApprove

safeApprove 因为重入 + 兼容性问题被废除——forceApprove 通过先 approve(0) 再 approve(amount) 解决。

六、Proxy / Upgradeability 的整理

升级合约用 ERC-1967 原生槽

5.x 完全用 EIP-1967 标准槽（不再有自定义实现）——所有可升级合约都用同一套 storage slot。

`Initializable` 的 `_disableInitializers`

1
2
3


constructor() {
 _disableInitializers(); // 防止 implementation 合约被攻击者初始化
}

这是必须做的——否则 implementation 合约本身可能被外部直接 init（Parity Wallet 2017 年就因为这个被 self-destruct，14 万 ETH 永久冻结）。5.x 的 Initializable 加了更严格的检查。

七、新增模块

Multicall

1
2
3
4
5
6
7


contract MyContract is Multicall { ... }

// 一笔交易里调多个本合约函数
multicall([
 abi.encodeCall(MyContract.func1, (...)),
 abi.encodeCall(MyContract.func2, (...))
]);

节省 Gas、保证原子性——很多 DeFi 协议自己实现 Multicall，5.x 提供了官方版本。

Nonces

1
2
3
4


contract MyContract is Nonces { ... }

// 防 replay 的 nonce 管理标准化
uint256 nonce = _useNonce(user);

ERC-2612 permit、EIP-712 签名场景的标配。

ERC4337（账户抽象）

5.x 提供基础组件，让你能更容易地实现 ERC-4337 智能账户。

ERC2771 Forwarder

支持 meta-transaction（用户不付 Gas，relayer 代发）。

ERC-7201 命名空间存储（Namespaced Storage）

contracts-upgradeable 包里全面改用 ERC-7201 命名空间存储布局，取代原来的 __gap 模式：

1
2
3
4
5


// 5.x 风格
/// @custom:storage-location erc7201:openzeppelin.storage.MyContract
struct MyContractStorage {
 uint256 value;
}

每个合约的 storage 字段被收进一个独立 struct，slot 由 keccak256(namespace) - 1 派生——升级加字段不再受顺序约束，老项目从 __gap 模式迁移过来要小心 storage layout 兼容。这是 5.x 在升级合约存储模型上最大的改动。

八、删除的东西

1. 一些低使用率的工具

MerkleProof 内部实现优化，但 API 兼容；Address.isContract 删除（用 code.length > 0 替代）。

2. `Counters` 库

1
2
3
4
5
6
7
8


// 4.x
using Counters for Counters.Counter;
Counters.Counter private _id;
_id.increment();

// 5.x
uint256 private _id;
_id++;

随着 Solidity 0.8+ 内置溢出检查，Counters 已经没意义——直接用 uint256 + ++。

3. `Address.functionDelegateCall`

整体 Address 库被简化——某些 helper 函数移除或重命名。

九、Governor 的全面重构

DAO 治理的 Governor 模块——4.x 的复杂度被 5.x 大幅简化：

1
2
3
4
5
6
7
8
9


// 5.x
contract MyGovernor is
 Governor,
 GovernorSettings,
 GovernorCountingSimple,
 GovernorVotes,
 GovernorVotesQuorumFraction,
 GovernorTimelockControl
{ ... }

mixin 数量更精简、API 更一致——做 DAO 的项目必看。

十、安全增强

1. 更严格的 reentrancy 检查

5.0 的 ReentrancyGuard 仍是普通 storage 实现（5.0 发布时 EIP-1153 transient storage 还未上链；EIP-1153 随 Cancun 升级在 2024-03 才上线主网）。5.1（2024-10）之后新增了独立的 ReentrancyGuardTransient 合约——基于 EIP-1153 transient storage，gas 显著降低（普通版热槽约 5000 gas，transient 版约 200 gas）。

1
2
3
4
5


// 5.0+：普通版
import "@openzeppelin/contracts/utils/ReentrancyGuard.sol";

// 5.1+：transient 版（更省 gas，但需 EVM 支持 EIP-1153）
import "@openzeppelin/contracts/utils/ReentrancyGuardTransient.sol";

2. Permit 标准化

ERC-2612 (permit) 在 5.x 默认开启更严格的签名校验。

3. 改进的 ECDSA 验证

签名相关的工具类（ECDSA、SignatureChecker）的 API 更清晰，避免 recover 返回 0 地址不被察觉的隐患。

十一、升级实战 Checklist

老项目升 5.x 的清单：

Solidity 升到 0.8.20+
Ownable 子合约改构造函数
_setupRole → _grantRole
_beforeTokenTransfer / _afterTokenTransfer → _update
safeApprove → forceApprove
删除 Counters，用 uint256 +1
删除 Address.isContract，用 addr.code.length > 0
可升级合约的 implementation 加 _disableInitializers()
Governor 子合约重写
完整跑 audits / tests

工具：

1
2


# 用 OpenZeppelin 的 upgrade tool
npx @openzeppelin/upgrades migrate

未必能自动改全——手工 review 仍然必须。

十二、新项目的最佳实践

如果你是从 0 起步——直接用 5.x。几条建议：

1. 用 ERC-1967 标准的可升级合约

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


import "@openzeppelin/contracts-upgradeable/proxy/utils/Initializable.sol";
import "@openzeppelin/contracts-upgradeable/access/OwnableUpgradeable.sol";

contract MyContract is Initializable, OwnableUpgradeable {
 /// @custom:oz-upgrades-unsafe-allow constructor
 constructor() {
 _disableInitializers(); // ⚠️ 必加：防止 implementation 合约被外部 init
 }

 function initialize(address initialOwner) public initializer {
 __Ownable_init(initialOwner);
 }
}

2. 永远 `_disableInitializers()`

3. 用 `using SafeERC20 for IERC20`

1
2


using SafeERC20 for IERC20;
token.safeTransfer(to, amount);

4. ReentrancyGuard 默认启用

任何接收/转账函数加 nonReentrant——5.1+ 优先用 ReentrancyGuardTransient（transient storage 版，每次开销约 200 gas），5.0 用普通版（gas 量级与 4.x 同）。

5. 关注 EIP-712 签名

权限调用 / 用户授权 / meta-tx——签名相关都用 OpenZeppelin 的 EIP-712 实现，别自己造。

十三、为什么这次升级值得

OpenZeppelin 4.x 系列已经是事实标准——5.x 升级带来的不是惊艳新功能，而是『更精简、更安全、更现代』。

具体收益：

代码量减少：单个 _update 替代两个 hook
更小 Gas：transient storage、内置优化
避免历史坑：forceApprove、_disableInitializers
DAO 治理更易用
新场景支持：ERC-4337、Multicall

小结

把全文压一句：

OpenZeppelin 5.0 不是『可选的小升级』——它是 Solidity 0.8.20+ 时代的事实标准，新项目应该直接采用，老项目应该规划迁移。

工程要点：

Ownable 构造函数必传 owner
ERC20 hook 改为 _update
safeApprove 用 forceApprove
Counters 删除，直接 uint256
可升级合约必加 _disableInitializers
永远去 OpenZeppelin GitHub 看 release notes

智能合约的"代码即资金"特性意味着——用过期的库 = 用过期的安全保护。OpenZeppelin 5.x 是当下应该用的版本。

数字身份的范式转移——DID 与 VC

Thu, 13 Mar 2025 15:30:00 +0800

写在前面

互联网时代的"身份"是一笔奇怪的账：

你的微信账号属于腾讯——封了你就没了
你的 Gmail 属于 Google——他们能 disable 你
你的银行账号属于银行
你的 LinkedIn 简历存在 LinkedIn 服务器

每一个"你的身份"，实际上都是某个公司租给你的。

DID（Decentralized Identifier，去中心化身份标识） 就是要解决这件事——让用户真正拥有自己的身份。

W3C 在 2022 年发布了 DID 1.0 规范，正式成为推荐标准。配合 Verifiable Credentials（可验证凭证） 规范，DID 是数字身份的范式转移——不只是 Web3 的玩具，而是有可能重塑互联网身份模型的基础设施。

本文讲清楚 DID 的结构、几种主流实现方法、可验证凭证的玩法、工程上的意义。

一、DID 长什么样

DID 是一种 URI——格式：

1

did:method:identifier

例子：

1
2
3
4


did:ethr:0x3b0BC51Ab9De1e5B7B6E34E5b960285805C41736
did:web:example.com:user:alice
did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK
did:ion:EiClkZMDxPKqC9c-umQfTkR8...

每段含义：

did：固定前缀
method：用什么"方法"实现这个 DID（决定了它在哪解析、什么类型的密钥等）
identifier：方法内的唯一标识

DID 是一个『可解析的身份标识』——给定一个 DID，你能解析出对应的"DID Document"，包含：

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


{
 "@context": "https://www.w3.org/ns/did/v1",
 "id": "did:ethr:0x3b0BC51A...",
 "verificationMethod": [{
 "id": "did:ethr:0x3b0BC51A...#controller",
 "type": "EcdsaSecp256k1RecoveryMethod2020",
 "controller": "did:ethr:0x3b0BC51A...",
 "blockchainAccountId": "eip155:1:0x3b0BC51A..."
 }],
 "authentication": ["did:ethr:0x3b0BC51A...#controller"],
 "assertionMethod": ["did:ethr:0x3b0BC51A...#controller"],
 "service": [{
 "id": "did:ethr:0x3b0BC51A...#hub",
 "type": "IdentityHub",
 "serviceEndpoint": "https://hub.example.com/users/alice"
 }]
}

DID Document 描述：

公钥（用于身份验证、签名）
服务端点（这个身份在哪里能联系到）
控制者（可能委托给别的 DID）

二、DID 的核心特性

1. 用户拥有

私钥在用户本地——没有任何中心化机构能"封禁"或"转让"DID。

2. 全局唯一

DID 在全球范围内唯一——不像 username 可能跨平台冲突。

3. 可解析

任何人拿到 DID 字符串都能查出 DID Document——拿到公钥、服务端点等元数据。

4. 可验证

DID Document 里的公钥可以验证签名——证明"这个 DID 的所有者真的是我"。

5. 可演化

私钥泄漏？可以更新 DID Document，启用新公钥废止老的——身份本身不变。

三、几种主流 DID 方法

DID 规范本身只是个"框架"——具体怎么实现叫"方法（method）"。每种方法有自己的 trade-off：

did:web

1

did:web:example.com:user:alice

最简单的方法——DID Document 就是 HTTPS 文件：

1

https://example.com/user/alice/did.json

特点：

✓ 极易部署，企业域名直接用
✓ 不依赖区块链
✗ 中心化（域名所有者能改 DID Document）
✗ 域名失效 DID 也失效

适合企业身份场景——不是真正去中心化，但合规、好用。

did:key

1

did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK

身份就是公钥本身——identifier 部分是公钥的 multibase 编码。

特点：

✓ 最简单的真正去中心化 DID
✓ 离线生成，不需要任何外部依赖
✗ 无法升级密钥——公钥泄漏 = 身份泄漏
✗ 没有服务端点

适合临时身份、单次签名场景。

did:ethr

1

did:ethr:0x3b0BC51Ab9De...

基于以太坊地址——身份注册和更新都通过智能合约。

特点：

✓ 真正去中心化，链上可验证
✓ 可以更新公钥（通过合约调用）
✗ 每次更新要付 Gas
✗ 严重依赖以太坊存活

did:ion

微软主导的 ION 网络——基于比特币的"侧链"层 2。

特点：

✓ 极致可扩展（每秒数千次操作）
✓ 几乎免费
✗ ION 自身是新基础设施

did:peer

适合"两人通信"场景——两端互相交换 DID，无需任何公开注册。

适合 P2P 通信、物联网设备身份。

四、Verifiable Credentials：DID 的杀手级用法

DID 解决了"你是谁"——但只是个标识。Verifiable Credentials（VC） 是 DID 的搭档——表达"某机构证明了你的某项属性"。

例子：大学学位证

 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


{
 "@context": [
 "https://www.w3.org/2018/credentials/v1",
 "https://www.w3.org/2018/credentials/examples/v1"
 ],
 "type": ["VerifiableCredential", "UniversityDegreeCredential"],
 "issuer": "did:web:university.edu",
 "issuanceDate": "2025-03-13T00:00:00Z",
 "credentialSubject": {
 "id": "did:ethr:0x3b0BC51A...",
 "degree": {
 "type": "BachelorDegree",
 "name": "Bachelor of Science in Computer Science",
 "university": "Example University",
 "year": "2025"
 }
 },
 "proof": {
 "type": "Ed25519Signature2020",
 "created": "2025-03-13T00:00:00Z",
 "verificationMethod": "did:web:university.edu#key-1",
 "proofPurpose": "assertionMethod",
 "jws": "eyJhbGciOi..."
 }
}

VC 的几个关键角色

flowchart LR
 Issuer[Issuer
大学] -->|颁发 VC| Holder[Holder
学生]
 Holder -->|出示 VC| Verifier[Verifier
HR/雇主]
 Verifier -.解析签名.-> Issuer

Issuer（颁发者）：大学、政府、银行
Holder（持有者）：用户自己，存在自己的钱包里
Verifier（验证者）：需要验证用户某项属性的方

VC 的革命性

传统流程：

求职者 → 雇主 → “请提供大学学位证明” → 学生联系大学 → 大学开纸质证明 → 寄给雇主 → 雇主再核实

VC 流程：

求职者持有数字 VC → 出示给雇主 → 雇主本地验证签名 → 完成

雇主不需要联系大学——签名就证明了真实性。用户掌握所有凭证——而不是分散在各机构数据库里。

五、零知识证明 + VC：选择性披露

VC 的最强组合是配合零知识证明——可以证明"我满足某个条件，但不暴露具体值"。

例子：买酒要证明已成年：

朴素：出示身份证 → 暴露具体生日、姓名、地址
VC + ZKP：证明"我的 VC 中 birthDate 早于今天减 18 年" → 没暴露任何具体数据

这种选择性披露是 DID + VC 在隐私保护上的杀手级能力——传统身份证根本做不到。

六、典型应用场景

1. 跨平台单点登录

不再用 Google / Apple 第三方登录——用自己的 DID 登录任何网站。网站只验证签名，不依赖第三方。

2. 数字证书

学位、驾照、护照、专业资格——所有"机构颁发的凭证"都能数字化为 VC。

3. 健康记录

疫苗证书、医疗记录——用户掌控、跨境通用、可被官方验证。

4. KYC 一次完成全平台用

Web3 的痛点之一——每个 dapp 都要 KYC。KYC 提供方颁发 VC，用户在每个 dapp 出示同一个 VC——验证一次，处处通用。

5. 物联网设备身份

每个 IoT 设备一个 DID——设备间相互验证身份，不需要中心化注册中心。

6. 内容真伪验证

媒体、政府公告签发 VC——读者验证签名确认内容来自真实来源（防 deepfake）。

七、工程上的挑战

DID + VC 想象很美，工程上挑战不少：

1. 用户体验

普通用户怎么"管理"自己的 DID？钱包是关键基础设施——但 Web3 钱包的体验目前对普通人不友好。需要更人性化的"DID 钱包"产品（如 Microsoft Authenticator、苹果 Wallet 都在向这个方向走）。

2. 私钥丢了怎么办

DID 完全去中心化的代价——没有"找回密码"。私钥丢失就身份永久丢失。社交恢复（social recovery）、多签等机制是部分解决方案。

3. 撤销机制

颁发的 VC 怎么撤销？比如学校发现学位是假的、银行注销账户。目前主流是颁发者维护一个"撤销列表"——验证时检查，但又中心化了。

4. 跨方法互操作

did:web / did:ethr / did:ion 等几十种方法——钱包要支持哪些？验证者要支持哪些？ 互操作性是大问题。

5. 合规

GDPR、个人信息保护法等监管对"链上不可删除的身份数据"有疑虑——DID 设计要明确"链上只放 hash 或公钥，PII 数据存链下"。

6. 普及度

DID 现在主要在 Web3 圈子用——主流互联网公司还没全面拥抱。

八、几个要关注的项目和标准

W3C DID 1.0 (w3.org/TR/did-core/)：核心规范
W3C Verifiable Credentials (w3.org/TR/vc-data-model/)：VC 规范
EBSI：欧盟区块链服务基础设施，已在多国部署 DID 应用
Microsoft Entra Verified ID：企业级 VC 平台
Polygon ID：基于以太坊侧链 + ZK 的 DID 解决方案
Ceramic Network：分布式数据网络，存 DID 关联数据
Veramo：JS SDK 给开发者用 DID + VC

九、对工程师意味着什么

如果你做的不是 Web3 项目——DID 仍然值得了解：

未来 5-10 年企业身份系统会逐步引入 VC——尤其大企业、政府
理解 DID 让你看清"中心化身份"的局限
DID 的设计哲学（私钥控制、自主主权、可验证）会渗透到普通互联网产品

如果你做 Web3 / dapp：

优先用 did:ethr 或 did:web——生态成熟
Sign-in with Ethereum (SIWE) 是 DID 的"轻量版"——Web3 应用先用 SIWE 替代第三方登录
用户钱包 = 身份——不要给用户搞另一套账号体系

小结

把全文压一句：

DID 把『你是谁』的控制权从平台还给用户——加上 VC 让任何机构能签发可验证的凭证——这是数字身份的范式转移。

理解 DID 的几个核心：

DID 是 URI 形式的身份标识
DID Document 描述身份元数据
VC 是对身份的"声明"
不同 DID 方法有不同 trade-off
配合 ZKP 实现选择性披露

DID 不是"现在就用"的技术——但它是值得每个工程师认知的未来基础设施。10 年后再回头看，这一定是数字身份史上的关键节点。

扫码登录的完整设计

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 共享状态

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

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

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 把这件事彻底下沉。

把这条链条闭环建好，未来无论加多少个服务、加多少种身份字段，业务代码都不用动。这才是"基础设施服务于业务"应有的样子。

不可变的合约如何「升级」？聊聊 Solidity 合约升级模式

Mon, 02 Sep 2024 20:00:00 +0800

一个让所有以太坊新手都困惑的悖论

智能合约最被反复强调的特性，是 不可变（immutable）——代码部署上链之后，一行都不能改。

但你只要在生产里跑过几个月就会发现一个现实：

代码会有 bug
业务会有新需求
协议会被攻击，要打补丁

这两件事看起来根本是矛盾的——承诺不可变，又必须能改。

整个"合约升级"这个话题，本质上就是在回答：怎么在不破坏不可变承诺的前提下，让合约的行为可以演进？

下面我们从最朴素的方案开始，一路讲到现在主流的代理模式、UUPS、Beacon、Diamond，把这些方案的来龙去脉、踩坑点和适用边界一次性讲清楚。

一、最朴素的方案：合约迁移（Contract Migration）

最直观的思路：既然合约不能改，那就部署一份新的。

流程大致是：

部署 TokenV2
写一个迁移脚本，把 TokenV1 上每个用户的余额读出来，写进 TokenV2
通知所有依赖方（前端、其他合约、CEX、用户）：地址换了，请用新的

这条路在小协议里偶尔还会用到，但作为通用方案，它的痛点很硬：

地址变了——所有依赖你的合约和应用都要改地址。DeFi 里这意味着流动性池要重建、用户授权要重做，几乎等于一次"硬分叉"。
状态迁移成本高——用户多的时候，光迁移就要几十万美元 Gas，且过程中可能有人在动账。
信任成本极高——用户怎么相信新合约里的余额没被篡改？

所以业界很快意识到：迁移不是"升级"，是"换房"。真正的升级，应该让地址不变、状态延续，只换"大脑"。

二、核心技巧：`delegatecall` 与代理模式

要做到"地址不变换大脑"，离不开 EVM 提供的一个特殊指令——delegatecall。

一句话理解 `delegatecall`

普通调用 call：用别人的代码、操作别人的存储。 delegatecall：用别人的代码、操作自己的存储。

也就是说，合约 A 通过 delegatecall 调合约 B 的某个函数时，执行的是 B 的字节码，但 msg.sender、msg.value、所有存储读写都发生在 A 上。

这就给了我们一个大胆的想法——

让一个只负责存数据的合约（Proxy），通过 delegatecall 把所有调用都转发给另一个只负责跑逻辑的合约（Logic）。

升级时只需要把 Proxy 指向的 Logic 地址换掉，Proxy 的地址和存储完全不变。

关系图

flowchart LR
 User([用户 / DApp])
 Proxy["Proxy 合约
(地址不变 + 存储)"]
 LogicV1["Logic V1
(纯代码)"]
 LogicV2["Logic V2
(升级后)"]

 User -- 调用 --> Proxy
 Proxy -- delegatecall --> LogicV1
 Proxy -. 升级后改指向 .-> LogicV2

一个最小可运行的代理

 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


contract MinimalProxy {
 address public implementation; // 当前指向的逻辑合约
 address public admin;

 constructor(address _impl) {
 implementation = _impl;
 admin = msg.sender;
 }

 function upgrade(address _newImpl) external {
 require(msg.sender == admin, "not admin");
 implementation = _newImpl;
 }

 fallback() external payable {
 address impl = implementation;
 assembly {
 calldatacopy(0, 0, calldatasize())
 let result := delegatecall(gas(), impl, 0, calldatasize(), 0, 0)
 returndatacopy(0, 0, returndatasize())
 switch result
 case 0 { revert(0, returndatasize()) }
 default { return(0, returndatasize()) }
 }
 }
}

fallback 把任何调用都 delegatecall 到 implementation。换 implementation 就等于升级。

看起来挺优雅，但魔鬼藏在细节里——存储布局。

三、升级最大的坑：存储布局冲突

delegatecall 操作的是 Proxy 的存储，但用的是 Logic 的代码。这就要求两件事：

Logic 合约里读写哪个存储槽，必须和 Proxy 里实际的存储槽对得上
升级前后两版 Logic 之间，存储槽不能错位

举个例子。假设 Logic V1 是这样：

1
2
3
4


contract LogicV1 {
 address public owner; // slot 0
 uint256 public totalSupply; // slot 1
}

某天我们想升级，写了个看起来合情合理的 V2：

1
2
3
4
5


contract LogicV2 {
 uint256 public totalSupply; // slot 0 ← 和 V1 的 owner 撞了！
 address public owner; // slot 1
 uint256 public newField; // slot 2
}

升级完，原来 owner 的位置被当成了 totalSupply，瞬间把一个地址解读成天文数字的代币总量——协议直接报废。

三条铁律

不能删除已有变量
不能调整变量顺序
不能改变量类型（包括 uint256 ↔ int256、定长数组长度等）

新版本想加字段？只能在末尾追加。

Storage Gap 习惯（OpenZeppelin 4.x 时代的做法）

时效性更新：本节描述的 __gap 模式是 OpenZeppelin 4.x 的标准做法。OpenZeppelin 5.0（2023-10）起的 contracts-upgradeable 包已经改用 ERC-7201 命名空间存储（Namespaced Storage Layout）——每个合约的 storage 字段被收进一个独立 struct，slot 从 keccak256(namespace) - 1 派生，升级加字段不再受顺序约束，也不再需要预留 __gap。新项目应该直接用 ERC-7201；老项目从 __gap 模式迁移到 ERC-7201 时要小心 storage layout 兼容。下面这段 __gap 写法仍然适用于 4.x 的基类继承场景（与 4.x 升级链路向后兼容）。

为了给未来"末尾追加"留余地，可继承的基类里通常会预留一段空槽：

1
2
3
4
5
6
7


contract MyUpgradeable {
 address public owner;
 uint256 public totalSupply;
 // ... 业务字段

 uint256[50] private __gap; // 给未来升级留 50 个槽
}

这是 OpenZeppelin 4.x 的标准做法。一旦未来要在基类加字段，就从 __gap 里"借"——既不破坏子类的存储布局，又不需要 fork 一份父类。

ERC-7201 的等价写法长这样（5.0+）：

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


contract MyUpgradeable {
 /// @custom:storage-location erc7201:myproject.storage.MyUpgradeable
 struct MyStorage {
 address owner;
 uint256 totalSupply;
 // ... 业务字段
 }

 // keccak256(abi.encode(uint256(keccak256("myproject.storage.MyUpgradeable")) - 1)) & ~bytes32(uint256(0xff))
 bytes32 private constant STORAGE_SLOT =
 0x...;

 function _s() private pure returns (MyStorage storage s) {
 bytes32 slot = STORAGE_SLOT;
 assembly { s.slot := slot }
 }
}

每个合约把自己的 storage 锁进独立命名空间——升级时加字段、调顺序、改基类继承都不会再撞槽。这是 5.x 在升级模型上最关键的一步。

升级前一定要做 storage layout 校验

存储布局错位的检查靠人肉是不现实的——升级链路必须有自动化校验把这个关。具体工具按你用的栈选：

Hardhat 栈：OpenZeppelin Upgrades Plugin（@openzeppelin/hardhat-upgrades）——升级前自动比对两版合约的存储布局，不兼容直接报错挡住。
Foundry 栈：openzeppelin-foundry-upgrades，或者直接 forge inspect <Contract> storageLayout 把新旧两版的 storage layout 输出成 JSON，在 CI 里做 diff。
更通用：Slither 的 slither-check-upgradeability 也能做静态布局比对。

形式不重要——一定要有一道自动检查。生产合约靠肉眼 review storage layout 早晚出事。

四、三种主流代理标准

代理模式发展到今天，演化出了三种主流形态。

1. Transparent Proxy（透明代理）

OpenZeppelin 早期推荐。它的核心问题是解决一个微妙的冲突——

如果 Proxy 自己有个函数叫 upgrade()，Logic 里也有个函数叫 upgrade()，用户调进来时到底是哪个执行？

Transparent Proxy 的解法是按调用者区分：

管理员调用 → 永远走 Proxy 自己的管理函数
普通用户调用 → 永远走 delegatecall 到 Logic

flowchart LR
 Admin([管理员]) -->|管理调用| ProxyAdmin["Proxy
(管理逻辑)"]
 User([普通用户]) -->|业务调用| ProxyDelegate["Proxy
(delegatecall)"]
 ProxyDelegate --> Logic["Logic 合约"]

简单可靠，但代价是 Proxy 里要存管理员判断逻辑，每次调用都多一次条件判断和 SLOAD，Gas 偏贵。

2. UUPS（ERC-1822，OZ 现在的默认推荐）

UUPS 的核心反转是——把升级逻辑搬进 Logic 合约。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


contract LogicUUPS {
 address public owner;

 function upgradeTo(address newImpl) external {
 require(msg.sender == owner, "not owner");
 // 通过 delegatecall 改的是 Proxy 自己的 implementation 槽
 assembly { sstore(_IMPL_SLOT, newImpl) }
 }
 // ... 其他业务函数
}

这样一来：

Proxy 极度精简，只有一个 fallback，Gas 最省
升级权限由 Logic 控制——这意味着 如果你升级到一个忘了写 upgradeTo 的新 Logic，合约就永远没法再升级了（一种"自爆开关"）

OpenZeppelin 现在更推荐 UUPS，但前提是开发者必须严格遵守"新版本永远要继承 UUPSUpgradeable“的规范，否则可能误锁死。

3. Beacon Proxy（信标代理）

前两种都是"一个 Proxy 对应一个 Logic”。如果你有 几百上千个同种合约（比如 Uniswap V3 工厂创建的众多池子），每次升级要逐一调用，成本难以承受。

Beacon Proxy 抽象出一个信标合约：

flowchart LR
 Beacon["Beacon
(只存当前 Logic 地址)"]
 Logic["Logic 合约"]

 P1["Pool Proxy 1"] -.读地址.-> Beacon
 P2["Pool Proxy 2"] -.读地址.-> Beacon
 P3["Pool Proxy ..."] -.读地址.-> Beacon

 P1 -.delegatecall.-> Logic
 P2 -.delegatecall.-> Logic
 P3 -.delegatecall.-> Logic

 Beacon -. 指向 .-> Logic

所有 Proxy 都从 Beacon 读"当前 Logic 地址"。升级时只改 Beacon 一处，所有 Proxy 同时生效。代价是每次调用多一次跨合约读地址的 Gas。

方案	Gas 开销	升级权限位置	适用场景
Transparent Proxy	较高	Proxy	单实例、追求稳定保守
UUPS	最低	Logic	单实例、追求性能（OZ 默认推荐）
Beacon Proxy	中等	Beacon	多实例、需要批量同步升级

五、更激进的方案：Diamond（EIP-2535）

EVM 对单个合约的字节码大小有 24KB 的硬上限（EIP-170）。当协议复杂到一个 Logic 合约塞不下时，前面那些"单 Logic"的代理模式就不够用了。

Diamond 模式的思路是——一个 Proxy（Diamond），多个 Logic（Facet），按函数选择器路由。

flowchart TB
 User([用户调用])
 Diamond["Diamond Proxy
(查路由表 + delegatecall)"]
 F1["Facet A
转账逻辑"]
 F2["Facet B
治理逻辑"]
 F3["Facet C
奖励逻辑"]
 F4["Facet ...
(可动态增删)"]

 User --> Diamond
 Diamond -- delegatecall --> F1
 Diamond -- delegatecall --> F2
 Diamond -- delegatecall --> F3
 Diamond -- delegatecall --> F4

每个 Facet 只实现一部分函数，Diamond 内部维护一张 selector → facet address 的路由表，调用进来时查表然后 delegatecall。升级时可以按 facet 增、删、换，粒度比单 Logic 细得多。

代价是复杂度陡升——存储布局要按"Diamond Storage"的命名空间约定写、调试链路更长、对应工具链不如 OZ 主流模式成熟。不是协议规模真的超过单合约能力，不要轻易上 Diamond（Aavegotchi 是公认上得最成功的案例之一）。

六、不能忽略的工程细节

1. 没有 constructor，只有 initializer

constructor 在合约部署时执行，只对 Logic 自己的存储生效，不会写到 Proxy 的存储。所以可升级合约的初始化必须放在一个普通函数里，靠只能调用一次的修饰符保护：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


contract MyLogic {
 bool private initialized;
 address public owner;

 function initialize(address _owner) external {
 require(!initialized, "already initialized");
 initialized = true;
 owner = _owner;
 }
}

OpenZeppelin 提供了 Initializable 基类，标准做法是用 initializer 修饰符。

2. 部署后立刻调用 initializer

如果部署完 Logic 不立刻初始化，任何人都可以抢先调一次 initialize 把自己设成 owner。这种漏洞历史上发生过多次。脚本部署 Proxy 时要用 atomicallyDeployAndInitialize 之类的封装，把"部署 + 初始化"放进同一个交易。

3. 升级权限 = 协议生死开关

控制 upgrade 的私钥，等于握有协议的全部资金权。任何成熟协议都会用：

多签：避免单点泄密
Timelock：提案到生效之间留出延迟（通常 24~72 小时），让用户有撤资时间
DAO 治理投票：进一步去中心化，把升级决策交给代币持有者

如果你看到一个号称"去中心化"的协议，升级权在一把单签钥匙上——它在技术上和中心化产品没有任何区别。

七、可升级的代价：安全与去中心化的张力

可升级合约的存在，本身就违反了"不可变"的初心。

管理员可以悄悄换掉 Logic，把所有用户的资金转走——这是真实发生过的攻击。
审计的难度被放大：用户审计了今天的代码，明天升级后等于审了个寂寞。
形式化验证、不可变指标都失效：协议的安全保证从"代码"层退化为"运营方信誉 + 治理流程"层。

所以业界有一种相反的声音：真正成熟的协议应当逐步放弃可升级性。Uniswap V2/V3 的核心合约就是不可升级的——它的迭代靠"部署新协议、用户自愿迁移"完成，代价高，但换来了最强的信任。

作为协议设计者，你需要问自己：

“这个合约的升级权，是不是协议安全的天花板？”

如果答案是"是"，那就要尽一切努力收紧它——多签、Timelock、治理、最终弃管。

作为协议用户，你也要学会问：

“这个合约能升级吗？升级权在谁手里？有 Timelock 吗？”

回答不出来的协议，本质上就是一个许可型应用，无论它前端多花哨。

小结

把这一整圈讲下来，回到最初那个悖论——

智能合约的不可变是承诺，但现实的演进是必需。升级模式就是在两者之间做工程妥协的产物。

四种主流方案的本质：

合约迁移：放弃地址不变，老老实实换房
Transparent Proxy / UUPS：地址不变，靠 delegatecall 把存储和代码解耦
Beacon Proxy：多个 Proxy 共享一个 Logic 指针，批量升级
Diamond：突破合约大小上限，按 facet 灵活增删

而无论用哪种方案，真正的难点从来不是合约怎么写，而是升级权怎么管。技术层面可升级是简单的，治理层面让用户敢用一个可升级的合约，才是更难、也更重要的命题。

一句话收尾：

可升级是工程能力，不可升级是产品承诺，怎么在两者之间找平衡，是每一个协议设计者要回答的问题。

Java 权限框架怎么选——Shiro 与 Spring Security 对比

Thu, 22 Jun 2023 16:00:00 +0800

一句话先把定位讲清楚

	Shiro	Spring Security
起源	Apache，2009	Spring 全家桶原生
设计哲学	简单、上手快、最小依赖	完备、可扩展、深度集成
体系庞大度	轻量	重量
默认特性	认证 + 授权 + Session + 加密	认证 + 授权 + 大量协议（OAuth2、CSRF、CORS、JWT）
学习曲线	平缓	陡峭
与 Spring 集成	适配良好但不"自家"	原生

简单说：

Shiro 是『来即用的工具』，Spring Security 是『全功能的框架』。

下面把这两套方案的差异、各自优劣、不同场景下的选型建议讲清楚。

一、概念结构对比

Shiro 的核心概念

flowchart LR
 Subject[Subject
当前用户] --> SecurityManager[SecurityManager
核心]
 SecurityManager --> Authenticator[Authenticator
认证]
 SecurityManager --> Authorizer[Authorizer
授权]
 SecurityManager --> SessionManager[SessionManager
会话]
 Authenticator --> Realm[(Realm
数据源)]
 Authorizer --> Realm

Subject：当前操作的用户主体
SecurityManager：所有功能的入口
Realm：连接用户/角色/权限数据源（DB、LDAP、缓存）

代码风格非常直观：

1
2
3
4


Subject subject = SecurityUtils.getSubject();
subject.login(new UsernamePasswordToken(username, password));
subject.checkRole("admin");
subject.checkPermission("user:delete");

Spring Security 的核心概念

flowchart LR
 Filter[FilterChainProxy] --> AuthFilter[Authentication Filter]
 AuthFilter --> AuthMgr[AuthenticationManager]
 AuthMgr --> Provider[AuthenticationProvider]
 Provider --> UDS[(UserDetailsService)]
 AuthFilter --> SC[SecurityContext]
 SC --> Authz[AccessDecisionManager]
 Authz --> Voter[Voter / AuthorizationManager]

FilterChainProxy：所有请求都过的过滤器链
AuthenticationManager / Provider：认证流水线
UserDetailsService：连数据源
SecurityContext：认证后的上下文（线程级）
AuthorizationManager：授权决策

业务里典型用法：

1
2
3
4
5
6
7


@PreAuthorize("hasRole('ADMIN')")
public void deleteUser(Long id) {
 userService.delete(id);
}

// 或者细粒度
@PreAuthorize("hasAuthority('user:delete')")

一眼看上去 Spring Security 概念多得多——这是它的本质特征：用更细分的角色解耦每一步。

二、特性能力对比

	Shiro	Spring Security
用户名密码登录	✓	✓
角色 / 权限模型	✓ 简洁	✓ 强（GrantedAuthority）
会话管理	✓ 内置 Session	✓ HttpSession + 自定义
记住我	✓	✓
加密工具	✓	✓
注解鉴权	✓ `@RequiresPermissions`	✓ `@PreAuthorize`
URL 鉴权	✓ ini / Java DSL	✓ Java DSL
OAuth2 / OIDC	△ 第三方扩展	✓ 原生
CSRF 防御	✗	✓ 默认开启
CORS	✗	✓
JWT	△ 第三方	✓ Resource Server / OAuth2 配套
多因子认证	△	✓
Method 级注解 SpEL	✓ 简单	✓ 强大（SpEL 全支持）
Reactive 支持	✗ 不支持	✓ WebFlux 原生

差距的几个关键点：

OAuth2 / OIDC：只要你的系统涉及第三方登录、单点登录、服务对接、API 鉴权，Spring Security 几乎是唯一现实选择。Shiro 也能做，但要拼装大量代码
CSRF / CORS：Shiro 不管这些，要自己写过滤器；Spring Security 默认就帮你做好了
JWT：两者都能做，但 Spring Security 5.x 之后 Resource Server 支持极完善
Reactive：WebFlux 项目根本不要考虑 Shiro

三、典型代码对比

同样是"用户名密码登录 + 检查权限"：

Shiro

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


// 配置 Realm
public class MyRealm extends AuthorizingRealm {
 @Override
 protected AuthorizationInfo doGetAuthorizationInfo(PrincipalCollection p) {
 String username = (String) p.getPrimaryPrincipal();
 SimpleAuthorizationInfo info = new SimpleAuthorizationInfo();
 info.setRoles(userService.getRoles(username));
 info.setStringPermissions(userService.getPermissions(username));
 return info;
 }

 @Override
 protected AuthenticationInfo doGetAuthenticationInfo(AuthenticationToken token) {
 UsernamePasswordToken upt = (UsernamePasswordToken) token;
 User user = userService.findByUsername(upt.getUsername());
 if (user == null) throw new UnknownAccountException();
 return new SimpleAuthenticationInfo(user.getUsername(), user.getPassword(), getName());
 }
}

// 业务里
Subject subject = SecurityUtils.getSubject();
subject.login(new UsernamePasswordToken("admin", "123456"));
subject.checkPermission("user:delete");

Spring Security

 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


// UserDetailsService
@Service
public class MyUserDetailsService implements UserDetailsService {
 @Override
 public UserDetails loadUserByUsername(String username) {
 User user = userService.findByUsername(username);
 if (user == null) throw new UsernameNotFoundException(username);
 return org.springframework.security.core.userdetails.User.builder()
 .username(user.getUsername())
 .password(user.getPassword())
 .authorities(user.getAuthorities())
 .build();
 }
}

// SecurityFilterChain
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
 return http
 .authorizeHttpRequests(auth -> auth
 .requestMatchers("/login").permitAll()
 .anyRequest().authenticated())
 .formLogin(Customizer.withDefaults())
 .csrf(Customizer.withDefaults())
 .build();
}

// 业务里
@PreAuthorize("hasAuthority('user:delete')")
public void delete(Long id) { ... }

Shiro 的代码更直观——但每件事都要你做主动调用；Spring Security 是"声明 + 自动连接"，刚开始绕，习惯了反而省心。

四、扩展性

Shiro：扩展点少而清晰

Shiro 把扩展点限定在几个核心接口：Realm、SessionManager、Authenticator、Filter。要做特殊认证（比如手机验证码登录）只需要自己写个 Token + 改 Realm。扩展边界小、写起来直接。

Spring Security：扩展点多但有学习曲线

Spring Security 有几十个可扩展点：AuthenticationProvider、UserDetailsService、SecurityContextRepository、AuthenticationEntryPoint、AccessDeniedHandler、各种 Filter……第一次接它的人会被这么多概念吓到。

但一旦熟悉了：

想要"OAuth2 + 数据库角色 + JWT 接口 + 表单登录"四种方式共存？只是几个 SecurityFilterChain 的事
想要把 Session 存进 Redis 实现集群登录？SecurityContextRepository 改一个就够
想要某个 URL 用一种鉴权方式、另一些用另一种？多 SecurityFilterChain 按顺序匹配

复杂场景下 Spring Security 远胜 Shiro——因为它把每件事都拆成了独立的扩展点。

五、社区与维护活跃度

	Shiro	Spring Security
主线版本	1.13.x（2024）	6.x，与 Spring 6 同步
发布频率	一年一两个小版本	跟 Spring Boot 节奏同步迭代
中文资料	较多（早期热门）	越来越多
国际社区	中等	强
招聘频率	中小厂偶尔提及	大厂、外企必考

国内 Shiro 用户多，是因为它早期太"友好"——五分钟上手，老项目就用了下来。但近年 Shiro 历史上爆出过多个 RCE 漏洞（CVE-2020-1957、CVE-2020-11989、CVE-2022-32532 等），这是用 Shiro 的项目必须持续关注版本升级的硬性事实。

Spring Security 漏洞同样有，但修复响应快、官方推送积极、版本管理跟着 Spring Boot 一起走——大型项目更省心。

六、性能差距：基本不存在

很多博客争论性能差距——这是个伪问题。

Shiro 和 Spring Security 都是"内存中读权限规则、过滤器链拦截请求"
性能瓶颈永远在你写的 Realm / UserDetailsService——也就是数据库查询
单次请求的鉴权耗时通常在几百微秒到 1ms 之间，业务代码随便就比这慢一个数量级

不要拿微基准跑出来的数字当选型依据。

七、什么场景选什么

选 Shiro 的场景

小到中型项目，权限模型简单（角色 + 几条权限）
不涉及 OAuth / SSO / 第三方登录
团队对 Shiro 已经熟悉、已有项目大量使用
不要 Reactive / WebFlux

选 Spring Security 的场景

需要 OAuth2、OIDC、SSO、JWT 等标准协议
大型 / SaaS / 多租户系统
有 WebFlux / Reactive 需求
新项目、想跟 Spring 全家桶生态保持一致
大厂面试 / 简历加分

八、共存与迁移建议

共存

老项目用 Shiro，新模块想用 Spring Security——理论上能共存，但强烈不推荐。两套过滤器链同时存在会很混乱，调试链路变长，维护成本极高。一个项目只用一套。

老项目从 Shiro 迁移到 Spring Security

迁移成本不小，但路径相对固定：

Realm → UserDetailsService + AuthenticationProvider
@RequiresPermissions → @PreAuthorize
Filter 配置改写成 SecurityFilterChain
Session 管理改 Spring Security 的 SecurityContext

要点：先打通主链路（登录 + 一个接口的鉴权），再批量替换注解——不要一口气全切。

九、几个被反复争论的话题

争论 1：Spring Security 太复杂

部分对——但它复杂的地方多数是"复杂功能不是你需要的功能"。基础的"账号密码登录 + 接口鉴权"配置极简：

1
2
3
4
5
6
7


@Bean
public SecurityFilterChain chain(HttpSecurity http) throws Exception {
 return http
 .authorizeHttpRequests(a -> a.anyRequest().authenticated())
 .formLogin(Customizer.withDefaults())
 .build();
}

是不是看起来比 Shiro 还少？

争论 2：Shiro 文档少

部分对——Shiro 官方文档质量一般，社区资料质量参差。Spring Security 文档有官方系统手册 + 大量社区文章，反而更容易学。

争论 3：Sa-Token 是不是更好的选择？

Sa-Token 是国内开源的轻量框架，API 极简，适合中小项目快速上手。它的定位更接近 Shiro——简单、易用、适合中小项目。

但 Sa-Token 的社区影响力和 Spring Security 不在一个量级，团队对接外部系统、招聘新人、跟进安全更新时仍然有差距。有兴趣可以学，但不要在大型项目里盲目替换主流框架。

十、决策树

flowchart TD
 Start([新项目?])
 Start -->|是| OAuth{需要 OAuth/SSO/第三方登录?}
 Start -->|否，老项目| Have{已经在用什么?}
 Have -->|Shiro 稳定| Keep[继续用，关注 CVE]
 Have -->|Spring Security| Keep2[继续用]
 OAuth -->|需要| SS1[Spring Security]
 OAuth -->|不需要| Reactive{用 WebFlux?}
 Reactive -->|是| SS2[Spring Security]
 Reactive -->|否| Scale{中长期会变复杂?}
 Scale -->|会| SS3[Spring Security]
 Scale -->|不会，工具型小项目| Choose[Shiro / Sa-Token / Spring Security 任选]

小结

把全文压一句：

Shiro 上手快、能力够、维护需谨慎；Spring Security 学习陡、能力全、生态强。中小项目都行，中大型项目优先 Spring Security。

工程上几条建议：

新项目优先 Spring Security——尤其涉及 OAuth/SSO 时
老项目用 Shiro 稳定运行的，不要折腾——但版本升级要跟住 CVE
不要两套共存——选一个，全量做
学权限框架不只是学 API，要学概念——用得好的关键是理解 Authentication / Authorization / Filter Chain / Context 这些底层概念
不要把"网上博客对比性能差几毫秒"当选型依据——那是噪声

把这两套之中任意一套用熟，配合好你的业务权限模型，安全这层基本就稳住了。

零知识证明入门——从直觉例子到 zk-Rollup

Wed, 08 Feb 2023 15:30:00 +0800

让 ZKP 变得直观的一个例子

零知识证明（Zero-Knowledge Proof，ZKP）听起来像是数学教授的玄学。但它要解决的问题，可以用一个生活化的场景描述：

小明给小红打电话：“我有这个保险柜的密码。” 小红怎么验证小明真的知道，又不想小明把密码告诉她？

朴素方案：小明把密码报给小红——但泄漏了密码。

零知识证明的方案：

小红把保险柜搬到一个房间里，柜子里放一张写着随机字符串的纸
小明进房间打开柜子，把纸上的字符串记下，再锁上柜子出来
小明把字符串报给小红——他能报出来，证明他确实开过柜子，但他没说密码

这就是 ZKP 的本质：

证明者（Prover）向验证者（Verifier）证明『某件事是真的』，过程中不泄漏任何额外信息。

本文从直觉到实战，把零知识证明、zk-SNARK、zk-Rollup 讲清楚——不需要数学基础。

一、零知识证明的三个性质

正式定义里 ZKP 必须满足三个性质：

完备性（Completeness）：如果命题为真，诚实的证明者一定能让诚实的验证者相信
可靠性（Soundness）：如果命题为假，作恶的证明者几乎无法让验证者相信（概率忽略不计）
零知识性（Zero-Knowledge）：验证过程不泄漏除"命题为真"以外的任何信息

第三点是最关键、最反直觉的——证明的过程绝对不能让验证者知道任何具体内容。

二、最经典的例子：Ali Baba 洞穴

1
2
3
4
5
6
7


 洞口
 |
 [岔路口]
 / \
 A B
 \ /
 [魔法门 - 需要密语]

小明（Prover）声称知道魔法门的密语。小红（Verifier）想验证。

验证流程

小红站在洞口外，不能看见岔路口
小明随机走 A 或 B 路径
小红走到岔路口，喊"从 A 出来"或"从 B 出来"
小明按要求出来
重复上述流程 N 次

为什么这是 ZKP

完备性：小明真的知道密语 → 100% 能按要求出来
可靠性：小明不知道 → 每次只有 50% 几率猜对，重复 30 次后猜对的概率是 (1/2)³⁰ ≈ 十亿分之一
零知识性：小红观察整个过程，只看到"小明能按要求出现"——没学到密语

这个洞穴比喻出自 Quisquater、Guillou、Berson 1990 年发表的 How to Explain Zero-Knowledge Protocols to Your Children （CRYPTO ‘89 论文集）。零知识证明本身的正式定义则更早——由 Goldwasser、Micali、Rackoff 在 1985 年的《The Knowledge Complexity of Interactive Proof-Systems》里给出。

三、互动式 vs 非互动式

上面的洞穴例子是互动式——验证需要双方反复来回。互动式 ZKP 有几个限制：

验证者必须在线
不能给第三方公开验证
不适合区块链场景

非互动式零知识证明（NIZK） 解决这些——Prover 一次性产出一个证明，任何人拿到都能验证。

1
2


Prover: ----proof----> Verifier
 (独立验证，无需 Prover)

NIZK 的关键技术是 Fiat-Shamir 变换——把 Verifier 的随机挑战换成对 Prover 提交的某种 hash，用 hash 的不可预测性替代真实的随机交互。

NIZK 是区块链应用 ZKP 的基础。

四、zk-SNARK：高效的 NIZK

ZKP 在理论上几十年前就有了，但实际能用是从 zk-SNARK 开始。

zk-SNARK = Zero-Knowledge Succinct Non-interactive ARgument of Knowledge

逐字解读：

Zero-Knowledge：零知识
Succinct：证明体积很小（几百字节）
Non-interactive：非互动
Argument of Knowledge：能"证明知道某个秘密"

它的实战意义——你能把任何复杂计算（如"这笔交易合法"）压缩成几百字节的证明，验证只要毫秒级。

Zcash：第一个商用案例

Zcash（2016）是第一个用 zk-SNARK 做"完全隐私交易"的区块链——

链上看到的是加密的发送方、接收方、金额
但每笔交易都附一个 SNARK 证明，证明这笔交易合法（没双花、有足够余额、签名正确）
验证者验证 SNARK，无需知道任何细节

链上数据完全隐私——但合法性能被任何节点验证。这是 ZKP 工程化最有代表性的应用之一。

五、ZKP 在以太坊：zk-Rollup

以太坊主网 TPS 低、Gas 贵——这是公链扩容的核心问题。Layer2 是主流方向，zk-Rollup 是其中最被看好的一种。

flowchart TB
 L2[(L2: 处理上千笔 tx)] --> Proof[生成 zk-SNARK
证明所有 tx 合法]
 Proof --> L1[L1 主网
验证证明 + 更新状态根]

zk-Rollup 的工作流：

Sequencer 在 L2 收集大量交易（数千笔）
在 L2 执行所有交易，得到新状态
生成一个 SNARK 证明——“我执行的所有交易都合法，新状态由旧状态正确得出”
把证明 + 新状态根提交到 L1
L1 验证 SNARK——验证通过则更新状态

为什么 zk-Rollup 比 Optimistic Rollup 强

维度	Optimistic Rollup	zk-Rollup
安全模型	假设没有作弊，挑战期内可证伪	数学证明，每次都验证
提款延迟	7 天（挑战期）	即时
验证成本	仅作弊时验证	每次都验证
证明生成成本	低（不需要）	高（需要 zk 电路）
适合 EVM	容易	难（zkEVM 是新课题）

zk-Rollup 的劣势是『证明生成成本高 + EVM 兼容难’——但生态正在快速进化（zkSync、StarkNet、Linea、Scroll 都是 zk 系 L2）。

六、ZKP 还能用来做什么

ZKP 的应用远不止隐私交易和扩容：

1. 隐私身份认证

证明"我已成年"——不告诉对方具体年龄。证明"我是某机构员工"——不告诉对方公司全部员工列表。

2. 私有投票

证明"我投了一票"——不告诉投了谁、不让人知道我是谁。

3. 数据隐私查询

证明"我的某项数据满足条件 X"——不暴露数据。

4. zkML（机器学习）

证明"模型 M 在输入 X 上得到了输出 Y"——不暴露模型权重或输入。

5. zk Bridge / zk Light Client

跨链桥用 ZKP 证明源链状态——避免传统跨链桥的多签信任假设。

证明"我有这个邮箱的访问权"——不暴露邮箱内容。

七、零知识证明的"证"和"建电路"

工程上做 ZKP 不是写一段普通代码——而是把要证明的命题翻译成『算术电路』。

1
2
3
4
5


要证：x² + y² < 100
↓ 翻译
电路：(x*x) + (y*y) - 100 < 0
↓ 用 zk DSL 写
ZKP 框架编译电路 + 生成证明

主流框架：

框架	特点
Circom	DSL 写电路，配 snarkjs 生成证明
Halo2	Rust 写电路，无需 trusted setup
Cairo	StarkNet 用，专为 STARK 设计
Noir	Aztec 出品，类 Rust 语法
Risc Zero	通用 zkVM，能跑任意 Rust 代码
SP1	通用 zkVM，类似 Risc Zero

一个 Circom 例子

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


template IsAdult() {
 signal input age;
 signal input minAge;
 signal output ok;

 component lt = LessThan(8);
 lt.in[0] <== minAge;
 lt.in[1] <== age + 1;
 ok <== lt.out;
}

写一段电路、编译出 wasm 和 r1cs 文件、用 snarkjs 给"输入"生成证明、上链验证。

八、ZKP 的代价和限制

ZKP 听起来万能，但代价不小：

1. 证明生成慢

复杂电路可能要几分钟到几小时才能生成一个证明——证明者侧的算力消耗大。

2. 证明体积小，但验证仍要 Gas

zk-SNARK 验证大约 200-500K gas——比传统验证贵，但比 Optimistic Rollup 的"挑战 + 仲裁"安全得多。

3. Trusted Setup 风险

部分 SNARK 方案（Groth16）需要 trusted setup——一组人共同生成参数，只要有一个参与者诚实，参数就安全。但这增加了信任成本。Halo2、PLONK、STARK 都不需要。

4. 电路开发门槛高

写电路是一种新范式——和写普通代码差别很大。需要的 bug 排查能力、性能调优能力都不同。

5. 工具链还在演进

调试器、IDE、profiler 工具都在快速发展中——但远不如传统编程成熟。

九、ZK-SNARK vs ZK-STARK

	SNARK	STARK
证明大小	小（KB 级）	中（数十 KB 到 MB）
验证速度	快	中
证明生成	中	快
Trusted Setup	多数需要	不需要
抗量子	✗	✓（基于 hash）
用例	Zcash、zkSync v2、Linea	StarkNet、Polygon Miden

工程上：SNARK 适合"证明 + 验证"链上场景（小证明、低 Gas），STARK 适合"高吞吐 + 强抗量子"场景。

十、了解了 ZKP，对工程意味着什么

作为应用开发者，你未必需要写电路——但你需要：

理解 ZKP 的能力边界——什么场景能用 ZKP，什么场景不能
知道 zk 系 L2 的取舍——zkSync / StarkNet / Linea 在什么场景胜过 Optimistic Rollup
理解隐私 / 合规的新可能——ZKP 让"既符合监管又保护用户隐私"在技术上可行

理解 ZKP 的工程价值不在于"会用 Circom"，而在于在产品设计时知道 ZKP 是一项可选武器。

小结

把全文压一句：

零知识证明让你能『证明你知道某件事，但不暴露具体内容』——把『可验证』和『隐私』这对看似矛盾的需求统一起来。

工程视角：

SNARK 是当下主流，但 STARK / Halo2 在崛起
zk-Rollup 被普遍认为是以太坊扩容最有前景的方向之一——但目前生态还在追赶 Optimistic
隐私身份、隐私投票、zkML 是未来 5 年最有想象力的方向
学 ZKP 不是必须会写电路——理解它的能力边界，知道何时使用，已经是巨大进步

零知识证明在 2010 年还主要停留在学术研究阶段，到 2020 年才在 Web3 工程中真正落地。**它正在重塑互联网中『可验证』和『隐私』的边界 **——值得每个工程师入门了解一次。

怎么设计一个生产级的验证码系统

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

不管哪一种，让"忘记加权限"在架构上不可能发生——这才是真正的数据权限设计。

用 Jackson 和 AOP 优雅地处理接口数据脱敏

Thu, 18 Feb 2021 15:30:00 +0800

这件事每个面向用户的接口都遇到

合规要求越来越严，业务接口里要返回手机号、身份证、邮箱、银行卡——但生产环境必须脱敏：

1
2
3
4


138****8000 原: 13800138000
510123****0023 原: 510123199001020023
z****@163.com 原: zhangsan@163.com
6228**********0023 原: 6228480000010990023

一个朴素的实现是在 Service 里手动转换：

1
2
3
4
5
6
7
8
9


public UserVO getUser(Long id) {
 User user = userRepo.findById(id).orElseThrow();
 UserVO vo = new UserVO();
 vo.setName(user.getName());
 vo.setPhone(MaskUtil.maskPhone(user.getPhone())); // 手动脱敏
 vo.setIdCard(MaskUtil.maskIdCard(user.getIdCard())); // 手动脱敏
 vo.setEmail(MaskUtil.maskEmail(user.getEmail())); // 手动脱敏
 return vo;
}

写一两次不烦——写到一百次必出错：

新人写新接口忘了脱敏 → 信息泄漏
字段重命名时 Util 的调用没改全 → 漏脱敏
测试环境不希望脱敏 → 各处 if 判断又加 bug
一个字段多个接口都返回 → 改脱敏规则要改一堆地方

正确姿势是——让脱敏变成"声明式"：

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


public class UserVO {
 private String name;

 @Sensitive(type = PHONE)
 private String phone;

 @Sensitive(type = ID_CARD)
 private String idCard;

 @Sensitive(type = EMAIL)
 private String email;
}

写一次注解，所有接口自动生效。本文讲清楚怎么用 Jackson 自定义序列化 + AOP 实现这套机制，以及生产环境的细节。

一、最朴素：用 Jackson 自定义序列化器

Spring Boot 默认用 Jackson 序列化 JSON——拦截这个过程是最干净的姿势。

1. 定义脱敏类型

1
2
3
4
5
6
7
8
9


public enum SensitiveType {
 PHONE,
 ID_CARD,
 EMAIL,
 BANK_CARD,
 NAME,
 ADDRESS,
 CUSTOM;
}

2. 定义注解

1
2
3
4
5
6
7
8
9


@Target(ElementType.FIELD)
@Retention(RetentionPolicy.RUNTIME)
@JacksonAnnotationsInside // 让自定义注解能携带其他 Jackson 注解
@JsonSerialize(using = SensitiveSerializer.class)
public @interface Sensitive {
 SensitiveType type();
 int prefix() default -1;
 int suffix() default -1;
}

@JacksonAnnotationsInside 是一个非常关键的"元注解"——它让 @Sensitive 自带 @JsonSerialize 的能力。

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
27
28
29
30
31
32


public class SensitiveSerializer extends JsonSerializer<String>
 implements ContextualSerializer {

 private SensitiveType type = SensitiveType.PHONE;
 private int prefix = -1;
 private int suffix = -1;

 public SensitiveSerializer() {}
 public SensitiveSerializer(SensitiveType type, int prefix, int suffix) {
 this.type = type;
 this.prefix = prefix;
 this.suffix = suffix;
 }

 @Override
 public void serialize(String value, JsonGenerator gen, SerializerProvider sp)
 throws IOException {
 if (value == null) { gen.writeNull(); return; }
 gen.writeString(SensitiveUtil.mask(value, type, prefix, suffix));
 }

 @Override
 public JsonSerializer<?> createContextual(SerializerProvider prov,
 BeanProperty property) {
 if (property == null) return this;
 Sensitive ann = property.getAnnotation(Sensitive.class);
 if (ann != null) {
 return new SensitiveSerializer(ann.type(), ann.prefix(), ann.suffix());
 }
 return this;
 }
}

ContextualSerializer 让序列化器能在每次使用时拿到字段上的注解参数——这是注解能"传参"的关键。

4. 实现脱敏工具

 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


public class SensitiveUtil {
 public static String mask(String src, SensitiveType type, int prefix, int suffix) {
 if (src == null || src.isEmpty()) return src;
 switch (type) {
 case PHONE:
 return src.length() == 11 ? src.substring(0, 3) + "****" + src.substring(7) : src;
 case ID_CARD:
 return src.length() == 18 ? src.substring(0, 6) + "********" + src.substring(14) : src;
 case EMAIL:
 int at = src.indexOf('@');
 if (at <= 1) return src;
 String name = src.substring(0, at);
 String mask = name.charAt(0) + "****";
 return mask + src.substring(at);
 case BANK_CARD:
 return src.length() < 4 ? src : "****" + src.substring(src.length() - 4);
 case NAME:
 return src.charAt(0) + "*";
 case ADDRESS:
 return src.length() <= 10 ? src : src.substring(0, 6) + "****";
 case CUSTOM:
 return maskCustom(src, prefix, suffix);
 default:
 return src;
 }
 }

 private static String maskCustom(String src, int prefix, int suffix) {
 if (src.length() <= prefix + suffix) return src;
 return src.substring(0, prefix)
 + "*".repeat(src.length() - prefix - suffix)
 + src.substring(src.length() - suffix);
 }
}

5. 实战使用

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


public class UserVO {
 private String name;

 @Sensitive(type = PHONE)
 private String phone;

 @Sensitive(type = ID_CARD)
 private String idCard;

 @Sensitive(type = EMAIL)
 private String email;

 @Sensitive(type = CUSTOM, prefix = 4, suffix = 4)
 private String bankCard;

 // getters / setters
}

业务代码原汁原味：

1
2
3
4
5
6
7


@GetMapping("/users/{id}")
public UserVO getUser(@PathVariable Long id) {
 User user = userRepo.findById(id).orElseThrow();
 UserVO vo = new UserVO();
 BeanUtils.copyProperties(user, vo); // 直接拷贝
 return vo; // 返回时 Jackson 自动脱敏
}

二、按角色控制是否脱敏

需求经常是这样：

普通用户调接口看到 138****8000；管理员调接口看到完整 13800138000。

注解里加一个"绕过角色"：

1
2
3
4


public @interface Sensitive {
 SensitiveType type();
 String[] bypassRoles() default {}; // 这些角色不脱敏
}

修改序列化器（在原有字段基础上加 bypassRoles，并在 createContextual 里读注解传进新实例）：

 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
36
37


public class SensitiveSerializer extends JsonSerializer<String> implements ContextualSerializer {

 private SensitiveType type = SensitiveType.PHONE;
 private int prefix = -1;
 private int suffix = -1;
 private String[] bypassRoles = new String[0]; // ★ 新增

 public SensitiveSerializer() {}
 public SensitiveSerializer(SensitiveType type, int prefix, int suffix, String[] bypassRoles) {
 this.type = type;
 this.prefix = prefix;
 this.suffix = suffix;
 this.bypassRoles = bypassRoles;
 }

 @Override
 public void serialize(String value, JsonGenerator gen, SerializerProvider sp)
 throws IOException {
 if (value == null) { gen.writeNull(); return; }
 Set<String> myRoles = UserContextHolder.current().getRoles();
 if (Arrays.stream(bypassRoles).anyMatch(myRoles::contains)) {
 gen.writeString(value); // 不脱敏
 return;
 }
 gen.writeString(SensitiveUtil.mask(value, type, prefix, suffix));
 }

 @Override
 public JsonSerializer<?> createContextual(SerializerProvider prov, BeanProperty property) {
 if (property == null) return this;
 Sensitive ann = property.getAnnotation(Sensitive.class);
 if (ann != null) {
 return new SensitiveSerializer(ann.type(), ann.prefix(), ann.suffix(), ann.bypassRoles());
 }
 return this;
 }
}

业务里：

1
2


@Sensitive(type = PHONE, bypassRoles = {"ADMIN", "RISK_OPS"})
private String phone;

三、Jackson 方案的限制

Jackson 序列化是 JSON 输出阶段 才介入——它解决了"返回给前端时脱敏"。但有些场景它不能覆盖：

入参脱敏（用户上传含敏感数据，落库前要脱敏）
写日志脱敏（日志里也不能完整打印身份证）
第三方接口调用脱敏（你不直接控制 JSON 序列化）

这些场景需要 AOP 配合。

四、AOP 方案：方法级数据转换

AOP 拦截 Controller / Service 方法，在方法返回后遍历返回对象，手动改写带 @Sensitive 的字段：

 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


@Aspect
@Component
public class SensitiveAspect {

 @AfterReturning(value = "@annotation(SensitiveResult)", returning = "result")
 public void after(JoinPoint pjp, Object result) {
 maskRecursively(result);
 }

 private void maskRecursively(Object obj) {
 if (obj == null) return;
 if (obj instanceof Collection) {
 ((Collection<?>) obj).forEach(this::maskRecursively);
 return;
 }
 for (Field f : obj.getClass().getDeclaredFields()) {
 Sensitive ann = f.getAnnotation(Sensitive.class);
 if (ann != null && f.getType() == String.class) {
 f.setAccessible(true);
 try {
 String v = (String) f.get(obj);
 f.set(obj, SensitiveUtil.mask(v, ann.type(), ann.prefix(), ann.suffix()));
 } catch (IllegalAccessException ignored) {}
 } else if (!f.getType().isPrimitive() && !f.getType().getName().startsWith("java.")) {
 f.setAccessible(true);
 try {
 maskRecursively(f.get(obj));
 } catch (IllegalAccessException ignored) {}
 }
 }
 }
}

调用方加注解：

1
2


@SensitiveResult
public List<UserVO> listUsers() { ... }

Jackson vs AOP

	Jackson	AOP
触发时机	JSON 序列化时	方法返回时
改的对象	输出流	Java 对象本身
后续可读	输出流写完即结束	对象被改了，后续逻辑读到脱敏值
性能	高	中（反射遍历）
控制粒度	字段级	方法级 + 字段级
适用	接口返回	入参、日志、复杂场景

生产推荐组合：Jackson 处理 99% 的接口返回，AOP 处理少数特殊场景。

五、踩坑提醒

1. 不要原地修改 Entity

AOP 方案里有个隐含风险——直接修改了 User 实体的字段：

1
2


List<User> users = userRepo.findAll();
maskRecursively(users); // 改了实体！

如果接下来还要把这些 users 写回 DB，会写入脱敏后的值——数据被破坏。

正确做法：只对 VO 脱敏，永不对 Entity。VO 是临时对象，Entity 是数据。

2. 注解要打在 String 上

Long、Integer 这些类型上加 @Sensitive 不会生效（序列化器只处理 String）——身份证存 String 不要存 Long。

3. 集合 + 嵌套对象

JSON 序列化器自动递归处理嵌套；AOP 方案要手动写递归，容易栈溢出——加个深度限制：

1
2
3
4


private void maskRecursively(Object obj, int depth) {
 if (depth > 10) return;
 // ...
}

4. 缓存的对象

如果对象被脱敏后又被放进缓存，缓存里的值就是脱敏的——下次拿出来给管理员也是脱敏的。永远只在最后一刻（接口返回）脱敏。

5. 日志里也要脱敏

1

log.info("user info: {}", user); // ❌ user.toString() 含完整手机号

可以为 Lombok 的 @ToString 用 @ToString.Exclude，或在 Logback 配 PatternMaskingFilter。

6. 测试环境不脱敏

通过 Profile 切换：

1
2
3
4
5


@Profile({"!test"})
@Configuration
public class SensitiveConfig {
 // 注册序列化器
}

测试环境关闭脱敏，方便调试。

7. 某些字段不脱敏 = 数据合规风险

不要让"业务方便"凌驾于合规之上——有人为了排查问题要"管理员能看完整信息"，要做：

操作日志（谁在什么时候查了谁的完整数据）
二次确认（点"查看完整"才显示）
限频（每天最多查 N 个）

六、生产推荐架构

flowchart TD
 Req[接口请求] --> Controller
 Controller --> Service[业务逻辑]
 Service --> DB[(DB 存原文)]
 Service --> VO[转 VO]
 VO --> Sensitive["@Sensitive 注解
(声明式)"]
 Sensitive --> Jackson[Jackson 序列化
自动脱敏]
 Jackson --> Resp[返回前端]
 
 Logging[日志记录] --> LogMask[Logback PatternFilter
脱敏]

每一层都有自己的脱敏机制，VO 上的注解是核心声明，序列化器/AOP/日志过滤器各自落实。

小结

把全文压一句：

数据脱敏不该写在业务代码里——它属于『数据展示层』的事。用注解声明字段类型，用 Jackson 序列化器或 AOP 做执行——业务代码只关心业务。

工程上几条铁律：

永远脱敏 VO，不脱敏 Entity
接口返回用 Jackson 序列化器，特殊场景用 AOP 兜底
日志脱敏单独走 Logback Filter
角色绕过要严格审计
测试环境通过 Profile 关闭

把这套做对，业务代码再也不用满地 MaskUtil.maskPhone(...)，新接口加字段也不会漏脱敏。

微信扫码登录三种方案对比：开放平台、公众号、扫码即登录

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 应用的"登录"问题基本就解决了。

安全防护 on 牛哥聊技术

OpenZeppelin Contracts 5.0 的关键变化

写在前面

一、最大变化：Solidity 0.8.20+ 基线

二、Ownable 必须传 initialOwner

三、AccessControl 的角色管理变了

_grantRole 移到 internal

hasRole 行为不变，但 getRoleMemberCount / getRoleMember 移到了 AccessControlEnumerable

四、ERC20 的 _beforeTokenTransfer / _afterTokenTransfer 删除

五、SafeERC20 的简化

六、Proxy / Upgradeability 的整理

升级合约用 ERC-1967 原生槽

Initializable 的 _disableInitializers

七、新增模块

Multicall

Nonces

ERC4337（账户抽象）

ERC2771 Forwarder

ERC-7201 命名空间存储（Namespaced Storage）

八、删除的东西

1. 一些低使用率的工具

2. Counters 库

3. Address.functionDelegateCall

九、Governor 的全面重构

十、安全增强

1. 更严格的 reentrancy 检查

2. Permit 标准化

3. 改进的 ECDSA 验证

十一、升级实战 Checklist

十二、新项目的最佳实践

1. 用 ERC-1967 标准的可升级合约

2. 永远 _disableInitializers()

3. 用 using SafeERC20 for IERC20

4. ReentrancyGuard 默认启用

5. 关注 EIP-712 签名

十三、为什么这次升级值得

小结

数字身份的范式转移——DID 与 VC

写在前面

一、DID 长什么样

二、DID 的核心特性

1. 用户拥有

2. 全局唯一

3. 可解析

4. 可验证

5. 可演化

三、几种主流 DID 方法

did:web

did:key

did:ethr

did:ion

did:peer

四、Verifiable Credentials：DID 的杀手级用法

例子：大学学位证

VC 的几个关键角色

VC 的革命性

五、零知识证明 + VC：选择性披露

六、典型应用场景

1. 跨平台单点登录

2. 数字证书

3. 健康记录

4. KYC 一次完成全平台用

5. 物联网设备身份

6. 内容真伪验证

七、工程上的挑战

1. 用户体验

2. 私钥丢了怎么办

3. 撤销机制

4. 跨方法互操作

5. 合规

6. 普及度

八、几个要关注的项目和标准

九、对工程师意味着什么

小结

扫码登录的完整设计

写在前面

一、整体流程

二、状态机

三、API 设计

1. 创建二维码

二、Ownable 必须传 `initialOwner`

`_grantRole` 移到 internal

`hasRole` 行为不变，但 `getRoleMemberCount` / `getRoleMember` 移到了 `AccessControlEnumerable`

四、ERC20 的 `_beforeTokenTransfer` / `_afterTokenTransfer` 删除

`Initializable` 的 `_disableInitializers`

2. `Counters` 库

3. `Address.functionDelegateCall`

2. 永远 `_disableInitializers()`

3. 用 `using SafeERC20 for IERC20`

二、核心技巧：`delegatecall` 与代理模式

一句话理解 `delegatecall`