后端 on Fallensakura715's Blog

订单幂等与支付回调改造

Thu, 15 Oct 2026 15:31:28 +0800

原项目的问题

原单体项目把订单服务拆出来后有几问题。

重复下单

原来的下单流程，每次执行generateOrder()，最终总会调用orderMapper.insert(order);，它没有识别这个请求是否曾经处理过，同一笔订单，重试一次就会多创建一次。
订单状态相互覆盖

如果支付和取消同时发生，后来的操作会覆盖前面的状态。订单刚支付完就有个取消请求，订单就会被直接取消，没有退款流程或者支付成功状态。

即：取消请求查到：订单待付款 -> 支付请求把订单改成已支付 -> 取消请求继续执行，把订单覆盖成已关闭。先查过待付款不能保证更新时仍然待付款。

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


public void cancelOrder(Long orderId) { 
 //查询未付款的取消订单 
 OmsOrderExample example = new OmsOrderExample(); 
 example.createCriteria()
		 .andIdEqualTo(orderId)
			.andStatusEqualTo(0)
			.andDeleteStatusEqualTo(0); 
 List<OmsOrder> cancelOrderList = orderMapper.selectByExample(example); 
 if (CollectionUtils.isEmpty(cancelOrderList)) { 
 return; 
 } 
 OmsOrder cancelOrder = cancelOrderList.get(0); 
 if (cancelOrder != null) { 
 //修改订单状态为取消 
 cancelOrder.setStatus(4); 
 orderMapper.updateByPrimaryKeySelective(cancelOrder); 
 OmsOrderItemExample orderItemExample = new OmsOrderItemExample(); 
 orderItemExample.createCriteria().andOrderIdEqualTo(orderId); 
 List<OmsOrderItem> orderItemList = orderItemMapper
		 .selectByExample(orderItemExample); 

		...
 } 
}

请求重试重复扣积分

原来下单之后会：
- 使用优惠券
- 扣积分
- 删除购物车商品
- 发送延迟取消消息

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


orderItemDao.insertList(orderItemList); 
if (orderParam.getCouponId() != null) { 
 updateCouponStatus(orderParam.getCouponId(), currentMember.getId(), 1); 
} 
if (orderParam.getUseIntegration() != null) { 
 order.setUseIntegration(orderParam.getUseIntegration()); 
 if(currentMember.getIntegration()==null){ 
 currentMember.setIntegration(0); 
 } 
 memberService.updateIntegration(currentMember.getId(), 
		 currentMember.getIntegration() - orderParam.getUseIntegration()); 
} 
deleteCartItemList(cartPromotionItemList, currentMember); 
sendDelayMessageCancelOrder(order.getId());

如果重试请求拿到原订单后，继续执行这些代码，仍然可能重复扣积分。

支付通知来了，直接把订单改成已支付

原来验签后直接拿订单号调用支付成功逻辑，缺少完整付款记录和校验。
如果订单金额不对，用户付了0.01元但是支付通知签名是真的，就能用0.01买走该订单商品。
如果支付宝没收到success通知，就会一直发送同一条通知，trade_no是同一个，每次通知都会跑一边paySuccess()流程，修改订单支付状态、扣库存。
或者同一张订单付了两次钱，交易号不同，多交的一笔钱会直接返回success支付成功，不会退款。

 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
38
39
40
41


public Integer paySuccess(Long orderId, Integer payType) { 
 OmsOrder order = new OmsOrder(); 
 order.setId(orderId); 
 order.setStatus(1); 
 order.setPaymentTime(new Date()); 
 order.setPayType(payType); 
 orderMapper.updateByPrimaryKeySelective(order); 
 
 OmsOrderDetail orderDetail = portalOrderDao.getDetail(orderId); 
 int count = portalOrderDao.updateSkuStock(orderDetail.getOrderItemList()); 
 return count; 
}

public String notify(Map<String, String> params) { 
 String result = "failure"; 
 boolean signVerified = false; 
 try { 
 //调用SDK验证签名 
 signVerified = AlipaySignature.rsaCheckV1(params, 
		 alipayConfig.getAlipayPublicKey(), 
		 alipayConfig.getCharset(), 
		 alipayConfig.getSignType()); 
 } catch (AlipayApiException e) { 
 log.error("支付回调签名校验异常！",e); 
 e.printStackTrace(); 
 } 
 if (signVerified) { 
 String tradeStatus = params.get("trade_status"); 
 if("TRADE_SUCCESS".equals(tradeStatus)){ 
 result = "success"; 
 log.info("notify方法被调用了，tradeStatus:{}",tradeStatus); 
 String outTradeNo = params.get("out_trade_no"); 
 portalOrderService.paySuccessByOrderSn(outTradeNo,1); 
 }else{ 
 log.warn("订单未支付成功，trade_status:{}",tradeStatus); 
 } 
 } else { 
 log.warn("支付回调签名校验失败！"); 
 } 
 return result; 
}

订单关闭后收到付款，又被强行改回待发货

本地超时任务关闭了订单之后，支付成功通知到达，验签就又会调用paySuccess()，执行一系列流程，把订单状态改成1。

设计下单幂等请求

由于上文讲到的问题，需要给下单请求加个唯一标识，让请求能安全地重试。还需要用户 ID ，把用户 ID 和客户端生成的请求幂等 key 作为联合主键去重，可以防止越权下单。

唯一键就是并发锁：

A 先 insert 成功，事务还没提交
B 的 insert 撞上唯一索引，会阻塞等待 A 的结果
A 提交：B 收到 DuplicateKeyException，进 catch，lock 读到 A 的 SUCCESS 记录并直接返回
A 回滚：B 的 insert 成功，B 接着创建订单

幂等前提是相同请求得到相同结果。如果同一个 key 带了不同参数，这就不是重试了，不能直接返回旧的订单，要对关键内容摘要做哈希(定长、省空间)，重放比对一致就是正常重试请求。

除此之外，需要标记下单请求处理进度。如果先插入幂等记录抢占 key，再创建订单。这时并发重试的第二个请求会因主键冲突失败，它需要知道第一个请求进行到哪了(库存和下单、优惠券的事务拆开了)：

state	含义	重试时的处理
PROCESSING	第一个请求还在处理	返回"处理中"，让客户端稍后重试或轮询
SUCCESS	订单已创建	直接返回 `order_id`
UNKNOWN	暂时没有可见记录，可能未提交	按业务决定：返回失败，或允许重置后重试

流程

INSERT
成功
1. 首次请求创建订单
2. 主键冲突 SELECT 幂等请求表
  1. hash 不同拒绝
  2. SUCCESS 返回 order_id
  3. PROCESSING 返回处理中
创建订单

建表

1
2
3
4
5
6
7
8


CREATE TABLE oms_order_request (
 member_id BIGINT NOT NULL,
 idempotency_key VARCHAR(64) NOT NULL,
 request_hash CHAR(64) NOT NULL,
 order_id BIGINT,
 state VARCHAR(16) NOT NULL,
 PRIMARY KEY(member_id, idempotency_key)
) ENGINE=InnoDB;

代码实现

SQL 和 DAO

Tips

lock 用 FOR UPDATE 有死锁的风险，InnoDB 里 insert 撞唯一键失败后，会对冲突的索引记录加 S 锁，持有到事务结束。

如果有两个以上的重复请求，各自持有 S 锁，都执行 SELECT ... FOR UPDATE ，把 S 升级成 X 两边互相等待对方释放 S 锁，其中一个被回滚。

重复请求只需要读最新数据，用共享锁读取即可，改成 FOR SHARE 。

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64


...
public interface OrderRequestDao {

 @Insert("""
 INSERT INTO oms_order_request (
 member_id, idempotency_key, request_hash, state
 ) VALUES (
 #{memberId}, #{key}, #{hash}, 'PROCESSING'
 )
 """)
 int insert(@Param("memberId") Long memberId,
 @Param("key") String key,
 @Param("hash") String hash);

 @Select("""
 SELECT member_id AS memberId,
 idempotency_key AS idempotencyKey,
 request_hash AS requestHash,
 order_id AS orderId,
 state
 FROM oms_order_request
 WHERE member_id = #{memberId}
 AND idempotency_key = #{key}
 """)
 Row find(@Param("memberId") Long memberId,
 @Param("key") String key);

 @Select("""
 SELECT member_id AS memberId,
 idempotency_key AS idempotencyKey,
 request_hash AS requestHash,
 order_id AS orderId,
 state
 FROM oms_order_request
 WHERE member_id = #{memberId}
 AND idempotency_key = #{key}
 FOR SHARE
 """)
 Row lock(@Param("memberId") Long memberId,
 @Param("key") String key);

 @Update("""
 UPDATE oms_order_request
 SET order_id = #{orderId}, state = 'SUCCESS'
 WHERE member_id = #{memberId}
 AND idempotency_key = #{key}
 AND request_hash = #{hash}
 AND state = 'PROCESSING'
 AND order_id IS NULL
 """)
 int complete(@Param("memberId") Long memberId,
 @Param("key") String key,
 @Param("hash") String hash,
 @Param("orderId") Long orderId);

 @Data
 class Row {
 private Long memberId;
 private String idempotencyKey;
 private String requestHash;
 private Long orderId;
 private String state;
 }
}

业务代码

并发请求可能等待唯一键锁。锁等待超时的处理放在后面的 Controller 中，不能在事务已经失败后继续写订单。

幂等记录要和订单必须同生共死，失败时要整体回滚。如果不是：

记录提交，订单失败，客户端用原 key 重试一直卡在PROCESSING。
订单提交，记录失败，重试查不到记录，重复下单和没有幂等记录表一样。

放进同一个事务后，订单创建失败，幂等记录一起回滚，MySQL 里什么都没留下。probe 返回 UNKNOWN，客户端可以放心用原 key 重新下单。

部分下单服务：

 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
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114


@Transactional(readOnly = true)
public OrderCreateParam probe(OrderRequestIdentity identity) {
	validateIdentity(identity);

	String hash = hash(identity);
	OrderRequestDao.Row row = requestDao.find(
			identity.memberId(), identity.idempotencyKey());

	return toResult(identity, hash, row);
}

@Transactional(rollbackFor = Exception.class)
public OrderCreateParam create(OrderCreateParam param) {
	if (param == null) {
		throw badRequest("下单参数不能为空");
	}

	OrderRequestIdentity identity = param.getIdentity();
	validateIdentity(identity);
	String hash = hash(identity);

	try {
		requestDao.insert(
				identity.memberId(),
				identity.idempotencyKey(),
				hash);
	} catch (DuplicateKeyException ex) {
		// 同会员、同 key 已存在。
		// 如果另一笔事务尚未提交，唯一键检查会等待其结果。
		OrderRequestDao.Row row = requestDao.lock(
				identity.memberId(), identity.idempotencyKey());

		if (row == null) {
			throw new IllegalStateException("幂等请求记录不存在");
		}
		return toResult(identity, hash, row);
	}

	// 以下分支只有首次插入请求记录的事务能够执行。
	OmsOrder order = param.getOrder();
	if (order == null
			|| !Objects.equals(order.getMemberId(), identity.memberId())
			|| order.getId() != null
			|| param.getOrderItemList() == null
			|| param.getOrderItemList().isEmpty()) {
		throw badRequest("订单或订单明细不合法");
	}

	// 创建状态由订单服务决定。
	order.setStatus(0);
	order.setDeleteStatus(0);
	order.setPaymentTime(null);

	// 调用另一个 Spring Bean，原 create() 的事务会加入当前事务。
	OrderCreateParam result = orderService.create(param);

	int changed = requestDao.complete(
			identity.memberId(),
			identity.idempotencyKey(),
			hash,
			result.getOrder().getId());

	if (changed != 1) {
		throw new IllegalStateException("幂等请求完成状态写入失败");
	}

	result.setIdentity(identity);
	result.setRequestState("SUCCESS");
	result.setCreated(true);
	return result;
}

private OrderCreateParam toResult(
		OrderRequestIdentity identity,
		String hash,
		OrderRequestDao.Row row) {

	OrderCreateParam result = new OrderCreateParam();
	result.setIdentity(identity);
	result.setCreated(false);
	result.setOrderItemList(List.of());

	if (row == null) {
		// 普通查询看不到未提交记录，不能断言请求从未发生。
		result.setRequestState("UNKNOWN");
		return result;
	}

	if (!hash.equals(row.getRequestHash())) {
		throw new ResponseStatusException(
				HttpStatus.CONFLICT,
				"同一个幂等键不能用于不同的下单参数");
	}

	if ("PROCESSING".equals(row.getState())) {
		result.setRequestState("PROCESSING");
		return result;
	}

	if (!"SUCCESS".equals(row.getState())
			|| row.getOrderId() == null) {
		throw new IllegalStateException("幂等请求状态异常");
	}

	OmsOrder order = orderService.getById(row.getOrderId());
	if (order == null) {
		throw new IllegalStateException("幂等记录对应的订单不存在");
	}

	result.setRequestState("SUCCESS");
	result.setOrder(order);
	result.setOrderItemList(orderService.getItems(order.getId()));
	return result;
}

Controller

不能在 Service 的 @Transcational 方法内部 catch 掉这个异常，Spring 看不到异常，会以为方法成功，尝试 commit，死锁时数据不一致可能已经回滚了，状态不一致了。

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


public OrderCreateParam create(OrderCreateParam param) {
 try {
 return requestService.create(param);
 } catch (CannotAcquireLockException ex) {
 // 进入这里时，requestService 的事务已经回滚。
 // 让客户端查询并使用原 key 重试。
 OrderCreateParam result = new OrderCreateParam();
 result.setIdentity(param.getIdentity());
 result.setRequestState("PROCESSING");
 result.setCreated(false);
 result.setOrderItemList(java.util.List.of());
 return result;
 }
}

门户服务里下单逻辑取消订单等逻辑都要修改。

长事务的缺点

锁持有时间变长。行锁需要到事务提交/回滚后才释放，需要修改只能排队，容易出现锁等待超时。所以要在 Controller 捕获 CannotAcquireLockException。
占数据库连接。容易堵住数据库连接，其他接口也拿不到连接，整个服务都慢。
死锁概率上升。
回滚耗时。

可以把幂等记录作为一个短事务先提交成 PROCESSING，订单走自己的事务，最后更新记录。但是，处理卡死在 PROCESSING 恢复的复杂度非常大(加个时间字段、CAS、定时任务)，~~我偷个懒先~~。

支付幂等

建表

核心思路就是把一笔真实的付款单独存成一条流水，用交易号唯一性保证同一笔钱只入账一次。

交易号在同一个渠道唯一，把 provider 和 trade_no 作为主键幂等判断。这样同一笔付款重复通知会抛异常，两条相同通知后一个 INSERT 阻塞等前一个事务结果，和订单幂等处理相似。

订单表维护三个状态：

状态	含义	什么时候出现
`RECEIVED`	已收到付款信息，事务内处理中	先插入这条记录，占住唯一键
`APPLIED`	已用于支付该订单	订单状态更新成功后，同一事务内改成这个
`REFUND_PENDING`	已收款，需要退款	订单已被另一笔付款支付、订单已关闭等，这笔钱无法履约

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


CREATE TABLE oms_order_payment (
 provider VARCHAR(16)
 CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
 trade_no VARCHAR(128)
 CHARACTER SET ascii COLLATE ascii_bin NOT NULL,
 order_id BIGINT NOT NULL,
 amount DECIMAL(18, 2) NOT NULL,
 state VARCHAR(32) NOT NULL,
 create_time DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
 PRIMARY KEY (provider, trade_no),
 KEY idx_order_id (order_id)
) ENGINE=InnoDB;

代码实现

notify 通知接收

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74


public String notify(Map<String, String> params) {
 try {
 boolean verified = AlipaySignature.rsaCheckV1(
	 params,
 alipayConfig.getAlipayPublicKey(),
 alipayConfig.getCharset(),
 alipayConfig.getSignType());

 if (!verified) {
 return "failure";
 }

 if (!Objects.equals(alipayConfig.getAppId(), params.get("app_id"))) {
 return "failure";
 }

 if (alipayConfig.getSellerId() == null
 || !Objects.equals(
 alipayConfig.getSellerId(),
 params.get("seller_id"))) {
 return "failure";
 }

 String tradeStatus = params.get("trade_status");

 if (!"TRADE_SUCCESS".equals(tradeStatus)
 && !"TRADE_FINISHED".equals(tradeStatus)) {
 // 非付款成功通知，不执行支付状态转换。
 return "success";
 }

 PaymentNotice notice = new PaymentNotice(
 params.get("out_trade_no"),
 params.get("trade_no"),
 new BigDecimal(params.get("total_amount")));

 OrderTransitionResult result = orderService.acceptAlipay(notice);

 if ("REFUND_PENDING".equals(result.result())) {
 // 订单服务已持久化待退款记录。
 // 后续退款流程处理，不能确认库存或强行改订单状态。
 log.warn(
 "付款已登记待退款，orderId:{}, tradeNo:{}",
 result.order().getId(),
 notice.tradeNo());

 return "success";
 }

 if ("PAID".equals(result.result())
 || "ALREADY_PAID".equals(result.result())) {

 Integer status = result.order().getStatus();
 if (Integer.valueOf(1).equals(status)
 || Integer.valueOf(2).equals(status)
 || Integer.valueOf(3).equals(status)) {

 Long orderId = result.order().getId();
 
 // 相同 reservationId 的重复确认必须幂等。
 // 如果上次状态已提交但确认库存失败，
 // 平台重试通知时仍可重试这里。
 inventoryService.confirm(
 SkuStockReserveParam.reservationIdForOrder(orderId),
 new SkuStockReserveParam.ReservationActionRequest(orderId));
 }
 return "success";
 }
 return "failure";
 } catch (Exception ex) {
 log.error("处理支付宝支付通知失败", ex);
 return "failure";
 }
}

订单校验

主要流程：

校验参数
锁订单行 (FOR UPDATE)，同一订单的两条通知会在这里排队，关闭订单也会锁订单行。
插入付款记录
锁付款记录，核对订单和金额，确认这个交易号对应的是不是同一订单、同一金额。
付款金额不对退款
看付款记录状态
- APPLIED：这笔钱以前已经用于支付订单，当前通知是重发，返回 ALREADY_PAID
- REFUND_PENDING：这笔钱以前已经被判定要退款，重发时返回同样的结果
- RECEIVED：刚插入的新记录，继续处理
条件更新订单，如果失败(关闭，或者被另一笔付款支付)不覆盖已有订单状态。

Tips

为什么先锁 oms_order 再操作 oms_order_payment ？

如果反过来，一旦有其他地方按订单查流水加锁，加锁顺序相反就会引发死锁。需要固定顺序，先订单后流水的加锁顺序防止死锁。

场景	acceptAlipay	notify
订单待付款，首次通知	`PAID`	确认库存，返回 success
同一交易号重发，已经入账	`ALREADY_PAID`	再确认一次库存（补偿），success
订单已关闭，或已被另一笔付款支付	`REFUND_PENDING`	打日志，success
同一交易号重发，之前已是待退款	`REFUND_PENDING`	打日志，success
订单金额不符	`REFUND_PENDING`	打日志，success
参数非法、订单不存在、交易号冲突	抛异常，整个事务回滚	catch 后返回 failure

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59


@Transactional(rollbackFor = Exception.class) 
public OrderTransitionResult acceptAlipay(PaymentNotice notice) { 
 if (notice == null 
 || !StringUtils.hasText(notice.orderSn()) 
 || !StringUtils.hasText(notice.tradeNo()) 
 || notice.tradeNo().length() > 128 
 || notice.amount() == null 
 || notice.amount().signum() <= 0 
 || notice.amount().stripTrailingZeros().scale() > 2) { 
 throw error(HttpStatus.BAD_REQUEST, "付款参数不合法"); 
 } 
 
 OmsOrder order = stateDao.lockByOrderSn(notice.orderSn()); 
 if (order == null) { 
 throw error(HttpStatus.NOT_FOUND, "订单不存在"); 
 } 
 
 try { 
 paymentDao.insert(notice.tradeNo(), order.getId(), notice.amount()); 
 } catch (DuplicateKeyException ex) { 
 // 重复通知仍需读取已有付款记录，核对订单、金额和处理状态。 
 } 
 
 OrderPaymentDao.Row payment = paymentDao.lock(notice.tradeNo()); 
 if (payment == null) { 
 throw new IllegalStateException("付款记录不存在"); 
 } 
 
 if (!Objects.equals(payment.getOrderId(), order.getId()) 
 || payment.getAmount().compareTo(notice.amount()) != 0) { 
 throw error(HttpStatus.CONFLICT, "该平台交易号已经绑定其他订单或金额"); 
 } 
 
 if ("APPLIED".equals(payment.getState())) { 
 return new OrderTransitionResult("ALREADY_PAID", order); 
 } 
 if ("REFUND_PENDING".equals(payment.getState())) { 
 return new OrderTransitionResult("REFUND_PENDING", order); 
 } 
 if (!"RECEIVED".equals(payment.getState())) { 
 throw new IllegalStateException("付款记录状态异常"); 
 } 
 
 if (order.getPayAmount() == null 
		 || order.getPayAmount().compareTo(notice.amount()) != 0) { 
 finishPayment(notice.tradeNo(), "REFUND_PENDING"); 
 return new OrderTransitionResult("REFUND_PENDING", order); 
 } 
 
 int changed = stateDao.markPaid(order.getId()); 
 if (changed == 1) { 
 finishPayment(notice.tradeNo(), "APPLIED"); 
 return new OrderTransitionResult("PAID", stateDao.lockById(order.getId())); 
 } 
 
 finishPayment(notice.tradeNo(), "REFUND_PENDING"); 
 return new OrderTransitionResult("REFUND_PENDING", 
		 stateDao.lockById(order.getId())); 
}

其它

跨服务最终一致性尚未完成。订单状态已提交后，确认或释放库存仍可能失败。返回失败让平台重试只能提供一条恢复路径，不能代替可靠事件和恢复任务。
积分、优惠券等外围操作仍存在中断窗口。例如订单创建提交后，门户还没扣积分就宕机，重试虽然不会重复下单，却也不会自动补做缺失操作，需要后续事件机制处理。

原单体项目主要只考虑了正常流程，但一旦把订单服务独立拆出来，网络超时重试、并发读写、回调乱序就会出现很多问题。幂等和状态机看似多写了不少防御性代码和冗余表，但在交易链路里，保证可靠性，永远比省事更重要。

并发下库存预占与扣减的问题

Fri, 11 Sep 2026 17:28:50 +0000

我翻了翻这个商城项目的库存代码，想把它改造成分布式微服务架构。

在分布式场景下，网络请求不能认为是可靠的，这包括请求超时，重复投递，消息乱序等等情况。这个项目的库存扣减防超卖并不是原子的，只维护一个lock_stock，无法解决库存预占幂等问题，库存属于哪个订单，取消请求应该释放哪一批库存。

原项目的问题

当前的锁库存是这么做的： lock_stock +quantity，SQL 没有判断剩余的库存，Service 若把 Mapper 的影响行数直接当成“预占成功”，这个返回值只能证明某一行被更新，不能证明库存充足，这非常容易超卖。无论 stock - lock_stock 是否足够，只要 SKU 存在，更新都可能成功。

 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


<update id="updateByPrimaryKeySelective" parameterType="com.macro.mall.model.PmsSkuStock"> 
 update pms_sku_stock 
 <set> 
 <if test="productId != null"> 
 product_id = #{productId,jdbcType=BIGINT}, 
 </if> 
 <if test="skuCode != null"> 
 sku_code = #{skuCode,jdbcType=VARCHAR}, 
 </if> 
 <if test="price != null"> 
 price = #{price,jdbcType=DECIMAL}, 
 </if> 
 <if test="stock != null"> 
 stock = #{stock,jdbcType=INTEGER}, 
 </if> 
 <if test="lowStock != null"> 
 low_stock = #{lowStock,jdbcType=INTEGER}, 
 </if> 
 <if test="pic != null"> 
 pic = #{pic,jdbcType=VARCHAR}, 
 </if> 
 <if test="sale != null"> 
 sale = #{sale,jdbcType=INTEGER}, 
 </if> 
 <if test="promotionPrice != null"> 
 promotion_price = #{promotionPrice,jdbcType=DECIMAL}, 
 </if> 
 <if test="lockStock != null"> 
 lock_stock = #{lockStock,jdbcType=INTEGER}, 
 </if> 
 <if test="spData != null"> 
 sp_data = #{spData,jdbcType=VARCHAR}, 
 </if> 
 </set> 
 where id = #{id,jdbcType=BIGINT} 
</update>

锁库存的时候并不能解决并发问题。整个 Java 方法不会自动变成数据库原子操作。假设 stock = 1、lock_stock = 0，请求 A 和 B 都可能读到 0，并分别把 1 写回数据库。数据库里最终甚至可能仍是 lock_stock = 1，但两个订单都收到了成功结果。这是一次丢失更新，库存数字已经无法反映真实的业务归属。如果改成没有条件的 lock_stock = lock_stock + 1，结果又会变成 lock_stock = 2，同样超过总库存。

1
2
3
4
5
6
7
8


private void lockStock(List<CartPromotionItem> cartPromotionItemList) { 
 for (CartPromotionItem cartPromotionItem : cartPromotionItemList) { 
 PmsSkuStock skuStock = skuStockMapper.selectByPrimaryKey(cartPromotionItem.getProductSkuId()); 
 skuStock.setLockStock(skuStock.getLockStock() + cartPromotionItem.getQuantity());
 // 如果这时候库存没了，还会继续预扣 
 skuStockMapper.updateByPrimaryKeySelective(skuStock); 
 } 
}

1
2
3
4


<sql id="Base_Column_List"> 
 id, product_id, sku_code, price, stock, low_stock, pic, sale, promotion_price, lock_stock, 
 sp_data 
</sql>

1

select <include refid="Base_Column_List" /> from pms_sku_stock where id = #{id,jdbcType=BIGINT}

没有预占流水记录，只有一个锁定库存数量字段。

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


CREATE TABLE `pms_sku_stock` (
 `id` bigint NOT NULL AUTO_INCREMENT,
 `product_id` bigint DEFAULT NULL,
 `sku_code` varchar(64) CHARACTER SET utf8mb3 COLLATE utf8mb3_general_ci NOT NULL COMMENT 'sku编码',
 `price` decimal(10,2) DEFAULT NULL,
 `stock` int DEFAULT '0' COMMENT '库存',
 `low_stock` int DEFAULT NULL COMMENT '预警库存',
 `pic` varchar(255) CHARACTER SET utf8mb3 COLLATE utf8mb3_general_ci DEFAULT NULL COMMENT '展示图片',
 `sale` int DEFAULT NULL COMMENT '销量',
 `promotion_price` decimal(10,2) DEFAULT NULL COMMENT '单品促销价格',
 `lock_stock` int DEFAULT '0' COMMENT '锁定库存',
 `sp_data` varchar(500) CHARACTER SET utf8mb3 COLLATE utf8mb3_general_ci DEFAULT NULL COMMENT '商品销售属性，json格式',
 PRIMARY KEY (`id`) USING BTREE
) ENGINE=InnoDB AUTO_INCREMENT=243 DEFAULT CHARSET=utf8mb3 ROW_FORMAT=DYNAMIC COMMENT='sku的库存';

订单A取消时，只知道要释放两件，但无法确认这两件是否属于订单A，这也会带来幂等问题，订单A的取消请求发了两次，就会增加四件，虚增库存。这也导致无法审计，难以实现超时释放库存。

为什么要预占库存

订单业务流程是先下单，再支付/取消，库存会发生变化。如果下单时直接扣库存，取消订单恢复库存的时候不知道扣了多少库存，增加一个预扣字段，就能解决，方便了订单状态管理，这就是预占库存。而且，下单和支付不是一个瞬时事务。如果不预占，用户下单后库存可能被其他人抢走。

但是，预占库存会带来一些问题：在秒杀或热门商品场景下，用户下单而不支付，会让很多库存锁定，正常买家无法正常下单。如果扣库存成功，订单服务挂了，可能出现库存减少但是没有订单的情况。

库存原子更新

这个项目目前是单体项目，一条SQL语句的执行是原子的，所以用条件更新即可防止超卖。

1
2


UPDATE ims_sku_stock SET lock_stock = lock_stock + #{quantity} 
WHERE sku_id = #{skuId} AND stock - lock_stock &gt;= #{quantity}

InnoDB 执行这条 UPDATE 时会对目标库存行加排他锁。并发请求会在这一行上串行，后到的请求会基于更新后的值再次判断条件。因此，“判断库存够不够”和“增加锁定数量”不会被其他事务插入，这一条SQL是原子的。

但是这原子更新就意味着有行锁，秒杀情况下会有大量请求竞争同一行的行锁，库存扣减与数据库交互，性能会受到数据库连接数，IO，锁等等的性能限制。

这条 SQL 解决了超卖，却没有解决幂等。相同请求执行两次，仍会把 lock_stock 增加两次。要识别相同请求，库存预占必须有业务身份。

库存预占幂等

幂等就是同一个业务执行很多次，但是业务效果和执行一次相同。前端的防连点更不能替代服务端幂等设计。

原项目有三个库存量：

stock：当前库存总量；
lock_stock：已预占、尚未确认成交的数量；
stock - lock_stock：当前可售数量。

下单时只增加 lock_stock。支付成功后，同时减少 stock 和 lock_stock；订单取消时只减少 lock_stock。已经确认成交后的退款或退货属于另一条入库流程，不能再调用预占释放接口。

只增加一个 lock_stock 字段仍然不够。它只能表示锁了多少库存，不知道是哪个订单锁的。因此需要一张预占单记录请求和状态，再用预占明细记录每个 SKU 的数量：

还需要设置一个过期字段，再加上扫描主动过期，防止库存被无限占用。

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


CREATE TABLE ims_reservation (
 reservation_id VARCHAR(64) PRIMARY KEY,
 order_id BIGINT NOT NULL,
 request_hash CHAR(64),
 state VARCHAR(16) NOT NULL,
 expires_at DATETIME(3) NULL COMMENT '预占过期时间',
 created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3),
 UNIQUE KEY uk_reservation_order(order_id)
) ENGINE=InnoDB;

CREATE TABLE ims_reservation_item (
 reservation_id VARCHAR(64) NOT NULL,
 sku_id BIGINT NOT NULL,
 quantity INT NOT NULL,
 PRIMARY KEY(reservation_id, sku_id)
) ENGINE=InnoDB;

reservation_id 由订单服务生成。同一个业务请求重试时必须继续使用原 ID，不能每次重试都生成新值。order_id 上的唯一索引进一步限制一个订单只能对应一张预占单。

request_hash 是发现幂等键被误用。服务先合并重复 SKU、按 sku_id 排序，再对订单号和明细计算 SHA-256。同一个 reservation_id 如果带着不同商品或数量再次请求，服务会返回参数冲突，而不是把它当成正常重试。

两张预占表属于同一个库存库时可以加外键，但在分库、归档或高并发写入场景中，外键也会增加迁移和写入约束。

库存预占与释放

预占单有状态迁移：

操作	允许的当前状态	结果	库存变化
`reserve`	`INIT`	`RESERVED`	`lock_stock += quantity`
重复 `reserve`	`RESERVED`	返回 `RESERVED`	无
`confirm`	`RESERVED`	`CONFIRMED`	`stock -= quantity`，`lock_stock -= quantity`
重复 `confirm`	`CONFIRMED`	返回 `CONFIRMED`	无
`release`	`RESERVED`	`RELEASED`	`lock_stock -= quantity`
重复 `release`	`RELEASED`	返回 `RELEASED`	无
`INIT` 是事务内部的中间状态。正常情况下，事务提交后外部只能看到 `RESERVED`；任一 SKU 库存不足时，整个事务回滚，已经增加的其他 SKU 锁定量和预占明细也会一起撤销。

confirm 和 release 都先执行：

1
2
3
4


SELECT order_id, request_hash, state
FROM ims_reservation
WHERE reservation_id = ?
FOR UPDATE;

FOR UPDATE把同一张预占单上的一行加悲观锁。支付确认和取消同时到达时，只有先拿到行锁的一方能完成终态迁移，另一方会看到新的状态并停止修改库存。

当支付和超时释放请求同时到达，如果业务要求按支付发生时间裁决，就要引入支付时间或订单状态作为额外依据，不能只依赖任务执行先后。

超时库存释放

预占成功时写入 expires_at，后端定时任务扫描：

1
2
3
4
5
6


SELECT reservation_id, order_id
FROM ims_reservation
WHERE state = 'RESERVED'
 AND expires_at <= NOW(3)
ORDER BY expires_at
LIMIT 100;

任务要逐条调用同一个 release 方法。这样人工取消、订单超时和任务重试共用一套幂等逻辑。多个库存服务实例可能同时扫到同一张预占单，但 SELECT ... FOR UPDATE 会将释放串行化，后到的实例只会读到 RELEASED。

定时任务需要从另一个 Spring Bean 调用 ReservationService.release，让调用经过 Spring 事务代理；不要在同一个类里用 this.release(...) 自调用。项目还需要启用 @EnableScheduling。

扫描任务解决的是库存服务内部的兜底释放。订单服务仍应在订单取消或支付超时时主动发送释放命令，定时扫描只负责处理漏发、延迟和服务故障留下的预占。

扫描时间要根据支付时限和数据库负载调整。

代码示例

预占库存

INSERT ... ON DUPLICATE KEY UPDATE 让重复请求失败，随后再锁定并检查已存在的预占单。多 SKU 请求使用 TreeMap 按 sku_id 排序，让不同事务尽量以相同顺序锁库存行，从而降低死锁概率。死锁仍可能由其他更新路径引入，生产环境还需要对数据库死锁异常做有限次数重试。

 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
38
39
40
41
42
43
44
45
46
47
48
49


@Transactional
public String reserve(String reservationId, long orderId, List<Line> lines) {
 validateIdentity(reservationId, orderId);
 Map<Long, Integer> quantities = normalize(lines);
 String hash = fingerprint(orderId, quantities);

 jdbc.update("""
 INSERT INTO ims_reservation(
 reservation_id, order_id, request_hash, state, expires_at
 )
 VALUES (?, ?, ?, 'INIT', TIMESTAMPADD(SECOND, ?, NOW(3)))
 ON DUPLICATE KEY UPDATE reservation_id = reservation_id
 """, reservationId, orderId, hash, reservationTtlSeconds);

 Header header = lockedHeader(reservationId, orderId);
 if ("RELEASED".equals(header.state())) {
 throw new ReservationStateException("RESERVATION_ALREADY_RELEASED");
 }
 if (!hash.equals(header.hash())) {
 throw new IllegalArgumentException("IDEMPOTENCY_PARAMETER_CONFLICT");
 }
 if (!"INIT".equals(header.state())) {
 return header.state();
 }

 for (Map.Entry<Long, Integer> entry : quantities.entrySet()) {
 int quantity = entry.getValue();
 int updated = jdbc.update("""
 UPDATE pms_sku_stock
 SET lock_stock = lock_stock + ?
 WHERE id = ? AND stock - lock_stock >= ?
 """, quantity, entry.getKey(), quantity);
 if (updated != 1) {
 throw new StockUnavailableException(entry.getKey());
 }

 jdbc.update("""
 INSERT INTO ims_reservation_item(reservation_id, sku_id, quantity)
 VALUES (?, ?, ?)
 """, reservationId, entry.getKey(), quantity);
 }

 jdbc.update("""
 UPDATE ims_reservation
 SET state = 'RESERVED', updated_at = NOW(3)
 WHERE reservation_id = ? AND state = 'INIT'
 """, reservationId);
 return "RESERVED";
}

支付后确认

确认时同时减少 stock 和 lock_stock。例如确认前 stock = 10、lock_stock = 2，可售库存是 8；确认两件后变为 stock = 8、lock_stock = 0，可售库存仍是 8。支付只是把两件商品从RESERVED转成CONFIRMED，不会再次占用可售库存。

 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


@Transactional
public String confirm(String reservationId, long orderId) {
 Header header = lockedHeader(reservationId, orderId);
 if ("CONFIRMED".equals(header.state())) {
 return "CONFIRMED";
 }
 if (!"RESERVED".equals(header.state())) {
 throw new ReservationStateException("RESERVATION_NOT_RESERVED");
 }

 for (Line line : items(reservationId)) {
 int updated = jdbc.update("""
 UPDATE pms_sku_stock
 SET stock = stock - ?, lock_stock = lock_stock - ?
 WHERE id = ? AND stock >= ? AND lock_stock >= ?
 """, line.quantity(), line.quantity(), line.skuId(),
 line.quantity(), line.quantity());
 if (updated != 1) {
 throw new IllegalStateException("INVENTORY_INVARIANT_BROKEN");
 }
 }

 jdbc.update("""
 UPDATE ims_reservation
 SET state = 'CONFIRMED', updated_at = NOW(3)
 WHERE reservation_id = ? AND state = 'RESERVED'
 """, reservationId);
 return "CONFIRMED";
}

取消后释放

释放数量来自 ims_reservation_item，而不是取消请求传入的数量。客户端因此无法多释放库存，同一取消请求重复执行也不会再次减少 lock_stock。

方法开头插入 RELEASED 还有一个用途：处理消息乱序。如果取消消息先到、预占消息后到，取消请求会先写入一张没有明细的 RELEASED 记录。迟到的 reserve 看到该状态后直接拒绝，不会在订单已经取消后重新锁库存。

这段逻辑只处理取消和预占之间的乱序。confirm 早于 reserve 时会被拒绝，因为没有预占明细可供确认。订单服务应在确认预占成功后才允许进入支付流程，并让同一 reservation_id 的命令按顺序投递。如果消息通道不能保证顺序，确认命令需要在预占完成后重试，不能跳过状态检查直接扣库存。

 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


@Transactional
public String release(String reservationId, long orderId) {
 jdbc.update("""
 INSERT INTO ims_reservation(
 reservation_id, order_id, request_hash, state, expires_at
 )
 VALUES (?, ?, NULL, 'RELEASED', NULL)
 ON DUPLICATE KEY UPDATE reservation_id = reservation_id
 """, reservationId, orderId);

 Header header = lockedHeader(reservationId, orderId);
 if ("RELEASED".equals(header.state())) {
 return "RELEASED";
 }
 if (!"RESERVED".equals(header.state())) {
 throw new ReservationStateException("RESERVATION_CANNOT_RELEASE");
 }

 for (Line line : items(reservationId)) {
 int updated = jdbc.update("""
 UPDATE pms_sku_stock
 SET lock_stock = lock_stock - ?
 WHERE id = ? AND lock_stock >= ?
 """, line.quantity(), line.skuId(), line.quantity());
 if (updated != 1) {
 throw new IllegalStateException("INVENTORY_INVARIANT_BROKEN");
 }
 }

 jdbc.update("""
 UPDATE ims_reservation
 SET state = 'RELEASED', updated_at = NOW(3)
 WHERE reservation_id = ? AND state = 'RESERVED'
 """, reservationId);
 return "RELEASED";
}

超时库存释放

示例

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


public List<ExpiredReservation> findExpired(int limit) {
	if (limit <= 0 || limit > 1000) {
		throw new IllegalArgumentException("INVALID_BATCH_SIZE");
	}
	return jdbc.query("""
			SELECT reservation_id, order_id
			FROM ims_reservation
			WHERE state = 'RESERVED' AND expires_at <= NOW(3)
			ORDER BY expires_at
			LIMIT ?
			""", (rs, rowNum) -> new ExpiredReservation(
			rs.getString("reservation_id"), rs.getLong("order_id")), limit);
}

 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


@Component
public class ReservationExpiryJob {
 private static final Logger LOGGER = LoggerFactory.getLogger(ReservationExpiryJob.class);

 private final ReservationService reservationService;
 private final int batchSize;

 public ReservationExpiryJob(
 ReservationService reservationService,
 @Value("${inventory.reservation-expiry-batch-size:100}") int batchSize) {
 this.reservationService = reservationService;
 this.batchSize = batchSize;
 }

 @Scheduled(fixedDelayString = "${inventory.reservation-expiry-scan-ms:5000}")
 public void releaseExpiredReservations() {
 for (ExpiredReservation reservation : reservationService.findExpired(batchSize)) {
 try {
 // release 通过 Spring 代理进入独立事务，多实例重复扫描也不会重复释放。
 reservationService.release(
 reservation.reservationId(), reservation.orderId());
 } catch (IllegalStateException ex) {
 // 支付确认可能与超时释放同时发生，最终状态由预占单行锁串行决定。
 LOGGER.info("Skip expired reservation {}, reason={}",
 reservation.reservationId(), ex.getMessage());
 } catch (RuntimeException ex) {
 LOGGER.warn("Failed to release expired reservation {}",
 reservation.reservationId(), ex);
 }
 }
 }
}

超时重试可靠性

微服务调用会出现响应超时，调用方如果没收到成功信息，不知道库存服务有没有提交事务。

有了幂等设计，也就是reservation_id，订单服务可以直接重试。

第一次请求没提交，重试正常预占
第一次已经提交没收到成功消息，重试发现RESERVED，直接返回当前状态
同一个 ID 被错误用到另一组商品，request_hash不一致返回冲突
订单已经取消，重试读到RELEASED，不会重新预占

确认和释放逻辑相同，调用方如果超时，继续用reservation_id重试，库存变化最多发生一次。

没有解决分布式事务

@Transactional 只覆盖库存服务自己的数据库，不能同时回滚订单库。以下故障仍然可能发生：

库存预占成功，订单服务在记录结果前挂了
订单取消成功，释放请求没有发出去
支付成功，确认库存的消息重复或延迟到达

一种常见做法是让订单服务在本地事务中同时写订单和 outbox 事件，再由后台任务可靠投递。库存服务按至少一次语义消费命令，并依靠 reservation_id 去重。库存服务处理完成后也可以用 outbox 发布预占结果，订单服务再幂等更新订单状态。

如果仍使用同步 HTTP，原则也不变：订单先落库，再调用库存；遇到超时就使用相同幂等键重试。预占成功但订单流程没有继续时，由主动补偿和 expires_at 兜底释放。

只有在调用方可靠地驱动状态变化、失败命令可以持续重试时，完整业务流程才真正闭环。库存库里的一个本地事务不能代替跨服务一致性方案。

行锁性能瓶颈

条件更新保证了正确性，也意味着热门 SKU 的请求会竞争同一行锁。数据库连接数、事务耗时、磁盘 IO 和锁等待都会限制吞吐量。这个问题不能靠优化 SQL 来消除。

不同的业务可以采用不同的方案。

普通商品场景通常先采用数据库条件更新，因为实现简单、数据源单一，也容易核对。秒杀场景可以考虑请求排队、Redis Lua 原子预扣、库存分段或令牌化，但这些方案会引入缓存和数据库之间的一致性、补偿及对账问题。优化前应先压测确认瓶颈，不能用一套尚未闭环的双写方案替换已经正确的数据库事务。

无论是否引入缓存，预占身份、状态机和幂等语义仍然需要保留。Redis 可以改变竞争发生的位置，不能替代“这批库存属于哪个订单”的业务记录。

先把数据库的库存，预占对账做得可靠，后续的消息可靠投递，缓存预扣和秒杀优化才有可核对和补偿的基础。

Spring 中 @Transactional 的生效条件与失效场景

Mon, 02 Feb 2026 11:08:38 +0000

某天订单系统出现了一个数据不一致问题：用户支付成功了，但订单状态没更新，优惠券却已经被核销。排查后发现，开发同学在 Service 中写了一个内部方法调用， @Transactional 悄无声息地失效了。

这类问题在实际开发中屡见不鲜。要彻底理解 @Transactional 为何失效，我们必须先搞清楚它是如何生效的。

@Transactional 的原理

声明式事务

@Transactional 的本质是 AOP 代理 + 事务拦截器。理解这一点是分析所有生效/失效场景的基础。

当我们在方法上标注 @Transactional 时，Spring 并不会对我们的代码做任何修改。它的魔法在于 代理模式。

Spring 在启动时会扫描所有带有 @Transactional 注解的 Bean，然后为这些 Bean 创建一个代理对象。当外部调用这个 Bean 的方法时，实际上调用的是代理对象，而不是原始对象。代理对象会在调用真实方法前后插入事务管理的逻辑。

没有代理时的调用链：

1

调用方 → 目标对象.方法()

有代理时的调用链：

1

调用方 → 代理对象.方法() → 开启事务 → 目标对象.方法() → 提交/回滚事务

这就是为什么 @Transactional 被称为"声明式事务"——你只需要声明（标注注解），Spring 帮你实现事务管理。但这也意味着， 如果调用绕过了代理对象，事务就不会生效。

代理实现的方式

Spring 支持两种代理方式：

JDK 动态代理：基于接口实现。如果你的 Bean 实现了接口，Spring 默认使用这种方式。代理对象和目标对象实现同一个接口，调用时通过接口方法进入代理逻辑。

CGLIB 代理：基于继承实现。如果你的 Bean 没有实现接口，Spring 会使用 CGLIB 生成一个目标类的子类作为代理。子类覆写了父类的方法，在覆写的方法中加入事务逻辑。

CGLIB 基于继承的特性决定了 final 方法无法被代理，子类无法覆写父类的 final 方法。

事务是如何被拦截和管理的

事务拦截器

Spring 事务的核心拦截器是 TransactionInterceptor，它实现了 MethodInterceptor 接口。每当代理对象的方法被调用时，都会先经过这个拦截器。

拦截器的工作流程如下：

解析事务属性：读取方法上的 @Transactional 注解，获取传播行为、隔离级别、超时时间、回滚规则等配置。
获取事务管理器：根据配置找到对应的 PlatformTransactionManager（如 DataSourceTransactionManager）。
开启事务：调用事务管理器的 getTransaction() 方法，根据传播行为决定是开启新事务还是加入已有事务。
执行业务方法：调用目标对象的真实方法。
处理执行结果：如果方法正常返回，提交事务；如果抛出异常，根据回滚规则决定回滚还是提交。

关键源码

事务的核心处理逻辑在 TransactionAspectSupport 类的 invokeWithinTransaction 方法中：

 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


protected Object invokeWithinTransaction(Method method, Class<?> targetClass,
 final InvocationCallback invocation) throws Throwable {
 
 // 第一步：获取事务属性
 // 这里会解析 @Transactional 注解的所有配置项
 TransactionAttributeSource tas = getTransactionAttributeSource();
 final TransactionAttribute txAttr = tas.getTransactionAttribute(method, targetClass);
 
 // 第二步：获取事务管理器
 final TransactionManager tm = determineTransactionManager(txAttr);
 
 // 第三步：创建事务（如果需要）
 TransactionInfo txInfo = createTransactionIfNecessary(ptm, txAttr, methodId);
 
 Object retVal;
 try {
 // 第四步：执行真实的业务方法
 retVal = invocation.proceedWithInvocation();
 }
 catch (Throwable ex) {
 // 第五步：异常处理——决定回滚还是提交
 completeTransactionAfterThrowing(txInfo, ex);
 throw ex;
 }
 
 // 第六步：正常返回时提交事务
 commitTransactionAfterReturning(txInfo);
 return retVal;
}

事务回滚规则

在 completeTransactionAfterThrowing 方法中：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


protected void completeTransactionAfterThrowing(TransactionInfo txInfo, Throwable ex) {
 if (txInfo.transactionAttribute.rollbackOn(ex)) {
 // 匹配回滚规则，执行回滚
 txInfo.getTransactionManager().rollback(txInfo.getTransactionStatus());
 }
 else {
 // 不匹配回滚规则，仍然提交！
 txInfo.getTransactionManager().commit(txInfo.getTransactionStatus());
 }
}

默认的回滚规则定义在 DefaultTransactionAttribute 中：

1
2
3


public boolean rollbackOn(Throwable ex) {
 return (ex instanceof RuntimeException || ex instanceof Error);
}

这意味着： 默认情况下，只有 RuntimeException 及其子类，以及 Error，才会触发回滚。 如果抛出的是 IOException、 SQLException 这类受检异常，事务会正常提交。

事务生效五个条件

@Transactional 生效必须同时满足的条件：

Bean 必须由 Spring 容器管理

这是最基本的前提。只有被 Spring 管理的 Bean，Spring 才有机会为其创建代理。如果你手动 new 了一个对象，或者类上没有 @Service、 @Component 等注解，那这个对象就是一个普通的 Java 对象，与 Spring 无关，自然也不会有事务能力。

方法必须是 public

Spring 在解析 @Transactional 注解时，会显式检查方法的访问修饰符。如果方法不是 public，注解会被直接忽略。

这个限制的原因与代理机制有关。JDK 动态代理只能代理接口方法（接口方法默认都是 public）；CGLIB 虽然理论上可以代理非 public 方法，但 Spring 为了保持一致性和明确性，统一要求必须是 public 方法。

必须通过代理对象调用

这是最容易踩坑的地方。即使前两个条件都满足了，如果调用方式绕过了代理对象，事务依然不会生效。典型的场景就是同一个类中的方法互相调用（后面会详细讲解）。

事务管理器必须正确配置

Spring 需要一个 PlatformTransactionManager 来实际管理事务。对于 JDBC 操作，通常是 DataSourceTransactionManager；对于 JPA，是 JpaTransactionManager。如果你使用 Spring Boot，自动配置通常会帮你搞定这一切。但在某些复杂场景（如多数据源），你需要手动指定使用哪个事务管理器。

底层存储引擎必须支持事务

事务是数据库层面的概念。如果你使用的存储引擎不支持事务（如 MySQL 的 MyISAM 引擎），那么无论 Spring 层面怎么配置，事务都不会生效。MySQL 请务必使用 InnoDB 引擎。

事务失效八个场景

同类中的内部方法调用

这是最常见、最隐蔽的失效场景。 假设有这样一段代码：

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


@Service
public class OrderService {
 
 public void createOrder(Order order) {
 // 保存订单
 saveOrder(order);
 // 绑定优惠活动
 bindPromotion(order); // 直接调用本类方法
 }
 
 @Transactional
 public void bindPromotion(Order order) {
 promotionDao.bindOrder(order);
 // 如果这里抛异常，期望回滚
 }
}

开发者的预期是 bindPromotion 方法有独立的事务，如果失败应该回滚。但实际上，这个事务根本不会生效。

原因分析：当外部调用 orderService.createOrder() 时，确实是通过代理对象进入的。但在 createOrder 方法内部调用 bindPromotion 时，此时的 this 指向的是目标对象（原始的 OrderService 实例），而不是代理对象。调用直接发生在目标对象内部，完全绕过了代理层的事务拦截器。

解决方案：

方案一：注入自身的代理对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Service
public class OrderService {
 
 @Autowired
 private OrderService self; // 注入自己，拿到的是代理对象
 
 public void createOrder(Order order) {
 saveOrder(order);
 self.bindPromotion(order); // 通过代理对象调用
 }
}

方案二：使用 AopContext 获取当前代理

1
2
3
4
5
6
7
8
9


@Service
public class OrderService {
 
 public void createOrder(Order order) {
 saveOrder(order);
 // 需要配置 @EnableAspectJAutoProxy(exposeProxy = true)
 ((OrderService) AopContext.currentProxy()).bindPromotion(order);
 }
}

方案三：将方法拆分到不同的类中这是最推荐的做法，既解决了自调用问题，也符合单一职责原则。

方法不是 public

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


@Service
public class UserService {
 
 @Transactional
 void updateUser(User user) { // 包级别访问权限
 userDao.update(user);
 }
 
 @Transactional
 protected void deleteUser(Long id) { // protected
 userDao.delete(id);
 }
 
 @Transactional
 private void innerUpdate(User user) { // private
 userDao.update(user);
 }
}

以上三种写法， @Transactional 都不会生效。Spring 在 AbstractFallbackTransactionAttributeSource 类中有明确的检查：

1
2
3


if (allowPublicMethodsOnly() && !Modifier.isPublic(method.getModifiers())) {
 return null; // 返回null表示没有事务属性
}

这个限制的设计初衷是：非 public 方法通常是内部实现细节，不应该暴露给外部调用。如果你需要事务，说明这个方法应该是一个对外的业务入口，理应是 public 的。

异常被 catch 后没有重新抛出

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


@Service
public class PaymentService {
 
 @Transactional
 public void processPayment(Payment payment) {
 try {
 paymentDao.save(payment);
 thirdPartyApi.charge(payment); // 可能抛异常
 } catch (Exception e) {
 log.error("支付失败", e);
 // 异常被吞掉了，方法正常返回
 }
 }
}

这段代码的问题在于： catch 块捕获了异常后，只是打印了日志，没有重新抛出。从事务拦截器的视角来看，方法正常执行完毕并返回了，没有任何异常抛出到方法边界之外。根据前面分析的源码逻辑，正常返回会触发 commitTransactionAfterReturning，事务被提交了。

解决方案：

方法一：重新抛出异常

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


@Transactional
public void processPayment(Payment payment) {
 try {
 paymentDao.save(payment);
 thirdPartyApi.charge(payment);
 } catch (Exception e) {
 log.error("支付失败", e);
 throw new RuntimeException("支付处理失败", e); // 重新抛出
 }
}

方法二：手动标记事务回滚

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Transactional
public void processPayment(Payment payment) {
 try {
 paymentDao.save(payment);
 thirdPartyApi.charge(payment);
 } catch (Exception e) {
 log.error("支付失败", e);
 // 手动标记当前事务需要回滚
 TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
 }
}

抛出了受检异常但没有配置 rollbackFor

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


@Service
public class FileService {
 
 @Transactional
 public void uploadFile(MultipartFile file) throws IOException {
 fileDao.saveMetadata(file);
 
 if (file.getSize() > MAX_SIZE) {
 throw new IOException("文件过大"); // 受检异常
 }
 
 storageService.store(file);
 }
}

这个方法抛出了 IOException，这是一个受检异常（Checked Exception），不属于 RuntimeException 的子类。根据默认的回滚规则，这个异常不会触发回滚，事务会正常提交。

正确写法：

1
2
3
4


@Transactional(rollbackFor = Exception.class) // 指定所有异常都回滚
public void uploadFile(MultipartFile file) throws IOException {
 // ...
}

或者更精确地指定：

1
2
3
4


@Transactional(rollbackFor = {IOException.class, BusinessException.class})
public void uploadFile(MultipartFile file) throws IOException {
 // ...
}

阿里巴巴 Java 开发手册建议， @Transactional 注解应该始终指定 rollbackFor = Exception.class，避免受检异常导致的意外提交。

类没有被 Spring 管理

1
2
3
4
5
6
7
8


// 注意：没有 @Service、@Component 等注解
public class StandaloneService {
 
 @Transactional
 public void doSomething() {
 // 这个类不是 Spring Bean，注解无效
 }
}

使用时如果手动创建实例：

1
2


StandaloneService service = new StandaloneService();
service.doSomething(); // 没有事务

这种情况下，Spring 根本不知道这个类的存在，自然也不会为它创建代理。 @Transactional 注解就是一个普通的注解标记，没有任何运行时效果。

多线程调用

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


@Service
public class BatchService {
 
 @Transactional
 public void batchProcess(List<Order> orders) {
 // 使用并行流处理
 orders.parallelStream().forEach(order -> {
 orderDao.save(order); // 每个线程独立，不在主事务中
 });
 
 // 或者手动创建线程
 new Thread(() -> {
 orderDao.save(someOrder); // 新线程，没有事务
 }).start();
 }
}

Spring 的事务信息是存储在 ThreadLocal 中的。 ThreadLocal 的特性是线程隔离：每个线程有自己独立的变量副本。当你创建新线程或使用并行流时，新线程无法访问主线程的事务上下文，因此它们的数据库操作是在没有事务的情况下执行的。

主线程中的事务回滚，不会影响子线程已经提交的操作；子线程的操作失败，也不会导致主线程事务回滚。数据一致性完全无法保证。

解决方案：避免在事务方法中使用多线程，或者为每个线程单独管理事务（但这样就不是同一个事务了）。

使用了 final 或 static

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


@Service
public class FinalService {
 
 @Transactional
 public final void finalMethod() {
 // CGLIB 无法覆写 final 方法
 }
 
 @Transactional
 public static void staticMethod() {
 // static 方法不属于实例，无法被代理
 }
}

对于 final 方法：CGLIB 通过继承目标类来创建代理，但子类无法覆写父类的 final 方法，因此事务拦截逻辑无法插入。

对于 static 方法：静态方法属于类而不是实例，代理对象拦截的是实例方法调用。你调用 FinalService.staticMethod() 时，根本不经过任何代理对象。

底层存储引擎不支持事务

现在 MySQL 默认是 InnoDB 存储引擎，但是如果你的 MySQL 表使用了 MyISAM 引擎：

1
2
3
4


CREATE TABLE orders (
 id INT PRIMARY KEY,
 amount DECIMAL(10,2)
) ENGINE = MyISAM;

MyISAM 引擎不支持事务。无论你的 Java 代码如何配置，数据库层面根本不会开启事务。Spring 的事务管理器以为自己在管理事务，实际上数据库根本不配合。

传播行为的困惑

 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


@Service
public class OuterService {
 @Autowired
 private InnerService innerService;
 
 @Transactional
 public void outerMethod() {
 orderDao.createOrder(order); // 操作1
 
 try {
 innerService.innerMethod(); // 这个方法会抛异常
 } catch (Exception e) {
 log.error("内部方法执行失败，但我想继续", e);
 }
 
 orderDao.updateOrderStatus(order); // 操作2，期望能执行
 }
}

@Service 
public class InnerService {
 
 @Transactional // 默认 REQUIRED 传播行为
 public void innerMethod() {
 // 做一些操作后抛出异常
 throw new RuntimeException("业务异常");
 }
}

开发者的预期是： innerMethod 失败后，我在外层 catch 住异常，继续执行后续逻辑。但实际运行时，当执行到 orderDao.updateOrderStatus 时，会抛出 UnexpectedRollbackException，提示事务已被标记为回滚。

原因分析：默认的传播行为是 REQUIRED，表示"如果当前存在事务，就加入该事务"。所以 innerMethod 和 outerMethod 实际上在同一个事务中。当 innerMethod 抛出 RuntimeException 时，事务被标记为 rollback-only（必须回滚）。即使你在外层 catch 住了异常，这个标记仍然存在。当 outerMethod 尝试正常返回时，事务管理器发现事务已被标记为必须回滚，于是抛出异常。

解决方案：如果希望内层方法的失败不影响外层事务，可以使用 REQUIRES_NEW 传播行为：

1
2
3
4


@Transactional(propagation = Propagation.REQUIRES_NEW)
public void innerMethod() {
 // 独立的新事务，回滚不影响外层
}

排查事务问题

开启事务调试日志

在 application.yml 中配置：

1
2
3
4


logging:
 level:
 org.springframework.transaction.interceptor: TRACE
 org.springframework.jdbc.datasource.DataSourceTransactionManager: DEBUG

代码中检查事务状态

1
2
3
4
5


@Transactional
public void someMethod() {
 boolean isActive = TransactionSynchronizationManager.isActualTransactionActive();
 log.info("当前是否在事务中: {}", isActive); // 应该输出 true
}

检查代理类型

1
2
3
4
5
6
7
8


@Autowired
private OrderService orderService;

public void checkProxy() {
 System.out.println(orderService.getClass().getName());
 // 如果是代理，会输出类似：
 // com.example.service.OrderService$$EnhancerBySpringCGLIB$$xxxxx
}

如果输出的是原始类名，说明没有被代理。

总结

核心原则：

理解代理机制： @Transactional 的生效依赖于 AOP 代理，任何绕过代理的调用都会导致失效。
让异常飞出去：事务的回滚依赖于异常抛出。如果你 catch 了异常，要么重新抛出，要么手动标记回滚。
明确指定 rollbackFor ：不要依赖默认的回滚规则，建议始终配置 rollbackFor = Exception.class。

@Transactional 的本质是通过代理在方法执行前后插入事务管理代码。理解了这一点，所有失效场景都能用"是否经过代理"和"异常是否抛出"这两个问题来分析。

Spring 是如何利用“三级缓存”解决循环依赖的?

Sun, 25 Jan 2026 13:40:57 +0000

什么是循环依赖

循环依赖就是你需要实例化 A 的时候，A 需要实例化 B ，实例化 B 又需要 A 的实例。这就像是一个“死锁”或者“无限递归”的过程。

在 Java 开发中，如果我们写出如下代码，必然会报 StackOverflowError：

1
2
3
4
5
6
7
8


public class A {
 private B b;
 public A() { this.b = new B(); } // 构造器里循环依赖，死锁
}
public class B {
 private A a;
 public B() { this.a = new A(); }
}

但在 Spring 中，使用 @Autowired 进行属性注入时，神奇的事情发生了：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


@Service
public class ServiceA {
 @Autowired
 private ServiceB serviceB;
}

@Service
public class ServiceB {
 @Autowired
 private ServiceA serviceA;
}

上述代码能完美运行。Spring 究竟施了什么魔法，打破了“鸡生蛋，蛋生鸡”的死循环？

答案在Spring Bean 的生命周期与三级缓存设计中。

Bean 的生命周期

要理解循环依赖，必须先明确 Bean 创建的两个关键步骤（简化版）：

实例化： 对应方法 createBeanInstance。执行构造函数 new Object()。此时对象已经存在于堆内存，但属性都是 null。这个对象被称为原始对象。
属性填充： 对应方法 populateBean。执行 @Autowired 注入，将依赖注入进去。如果依赖的对象还没创建，就会暂停当前 Bean 的创建，转而去创建依赖的 Bean。
初始化： 对应方法 initializeBean。执行 BeanPostProcessor 的后置处理（如 AOP 代理生成）、InitializingBean 接口回调等。

Spring 解决循环依赖的核心思想是：

将“实例化”和“属性填充”分开。
当 ServiceA 实例化后，虽然它还不完整（属性没填，初始化没做），但它的内存引用地址已经确定了。Spring 提前把这个 “早期引用” 暴露出来，让 ServiceB 先拿着引用，从而打通闭环。

三级缓存的结构

打开 DefaultSingletonBeanRegistry 类，Spring 使用了三个 Map 来存储 Bean，也就是所谓的“三级缓存”。

DefaultSingletonBeanRegistry.java

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


// 一级缓存：成品池。存放已经经历了完整生命周期(实例化 -> 属性填充 -> 初始化)的 Bean
private final Map<String, Object> singletonObjects = new ConcurrentHashMap<>(256);

// 二级缓存：半成品池。存放早已被实例化，但还没属性填充的 Bean
// 这里存放的对象，可能是原始对象，也可能是被 AOP 提前代理过的对象。
private final Map<String, Object> earlySingletonObjects = new HashMap<>(16);

// 三级缓存：工厂池。存放的是 ObjectFactory，是一个 Lambda 表达式
// 它的作用是：生成半成品的引用。如果有 AOP，它会生成代理对象；如果没有，它直接返回原始对象。
private final Map<String, ObjectFactory<?>> singletonFactories = new HashMap<>(16);

为什么需要三个 Map ？

一级缓存：毫无疑问，用于存放最终可用的 Bean。
二级缓存：为了保证单例的唯一性。
三级缓存：为了解决 AOP 代理问题。

很多人说“为了解决循环依赖”，这不全对。如果仅仅是为了解决循环依赖，两级缓存就够了。第三级缓存是为了解决 AOP 代理问题。

详看下文三级缓存

创建 Bean 的流程

假设我们要创建 Bean A，它依赖 B；而 B 又依赖 A。

此时发生的事

sequenceDiagram
 participant Main as Spring容器
 participant Cache1 as 一级缓存(Pool)
 participant Cache2 as 二级缓存(Early)
 participant Cache3 as 三级缓存(Factory)

 Note over Main: 1. 开始创建 A
 Main->>Main: 实例化 A (new A) 
 此时 A 是半成品
 Main->>Cache3: add(A 的工厂) 
 放入三级缓存
 
 Note over Main: 2. 填充 A 的属性，发现依赖 B
 Main->>Main: 开始创建 B
 Main->>Main: 实例化 B (new B)
 Main->>Cache3: add(B 的工厂)
 
 Note over Main: 3. 填充 B 的属性，发现依赖 A
 Main->>Cache1: get(A) -> 没找到
 Main->>Cache2: get(A) -> 没找到
 Main->>Cache3: get(A) -> **找到了!**
 
 Cache3-->>Main: 执行工厂逻辑，返回 A 的引用
 Main->>Cache2: 将 A 放入二级缓存
 Main->>Cache3: 删除 A 的三级缓存
 
 Note over Main: 4. B 获取到了 A (半成品)
 Main->>Main: B 初始化完成
 Main->>Cache1: B 放入一级缓存
 
 Note over Main: 5. A 获取到了 B (成品)
 Main->>Main: A 初始化完成
 Main->>Cache1: A 放入一级缓存

关键源码：getSingleton

当 B 需要注入 A 时，会调用 getSingleton("a")，这是一个递归查找的过程：

DefaultSingletonBeanRegistry.java

 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


protected Object getSingleton(String beanName, boolean allowEarlyReference) {
 // 1. 先去一级缓存拿
 Object singletonObject = this.singletonObjects.get(beanName);
 
 // 2. 如果一级没拿到，且 A 正在创建中 (isSingletonCurrentlyInCreation)
 // 只有发生了循环依赖，才会进入这个分支
 if (singletonObject == null && isSingletonCurrentlyInCreation(beanName)) {
 // 3. 去二级缓存拿
 singletonObject = this.earlySingletonObjects.get(beanName);
 
 // 4. 二级也没拿到，但允许提前引用 (allowEarlyReference = true)
 if (singletonObject == null && allowEarlyReference) {
 synchronized (this.singletonObjects) { // 加锁双重检查
 // ... 重复检查一级二级 ...
 
 // 5. 去三级缓存拿工厂
 ObjectFactory<?> singletonFactory = this.singletonFactories.get(beanName);
 if (singletonFactory != null) {
 // 6. 【关键】调用工厂的 getObject() 方法，生成对象
 // 这一步可能会触发 AOP 代理的提前创建
 singletonObject = singletonFactory.getObject();
 
 // 7. 升级：放入二级，移除三级
 // 为什么放二级？因为工厂执行一次就够了，
					// 如果还有 C 依赖 A，直接从二级拿这个已经处理好的对象即可。
 this.earlySingletonObjects.put(beanName, singletonObject);
 this.singletonFactories.remove(beanName);
 }
 }
 }
 }
 return singletonObject;
}

为什么需要三级缓存

如果 A 没有被 AOP 代理，确实二级缓存就够了：

实例化 A -> 放二级 -> 创建 B -> B 取二级里的 A -> B 完成 -> A 完成。

但是，如果 A 被 @Transactional 或 AOP 切面代理了呢？

在 Spring 中，正常的 AOP 代理是在 Bean 初始化后 的 BeanPostProcessor 中完成的。也就是说，代理对象通常是在生命周期的最后一步生成的。

这就出现了一个悖论：

正常流程：A 实例化 -> 属性填充 -> 初始化 -> 生成 A_Proxy -> 放入一级缓存。
循环依赖流程：A 实例化 -> 属性填充 -> B 需要 A -> B 此时就要拿到 A。
冲突点：如果 B 此时拿到的是 A 的原始对象，而最后 A 初始化完变成了 A_Proxy，那么：
- 单例池（一级缓存）里存的是 A_Proxy。
- B 对象里引用的却是 原始 A。
- 结果：当你调用 b.getA().method() 时，AOP 增强逻辑（如事务）失效。

三级缓存的 ObjectFactory 就是为了解决这个“时机”问题。 它提供了一个回调机制。

看一下放入三级缓存的那个 Lambda 表达式，Spring 在实例化 A 之后，立刻将其放入三级缓存：

AbstractAutowireCapableBeanFactory.java

1
2


// doCreateBean 方法内
addSingletonFactory(beanName, () -> getEarlyBeanReference(beanName, mbd, bean));

这个 getEarlyBeanReference 是核心：

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


protected Object getEarlyBeanReference(String beanName, RootBeanDefinition mbd, Object bean) {
 Object exposedObject = bean;
 if (!mbd.isSynthetic() && hasInstantiationAwareBeanPostProcessors()) {
 for (BeanPostProcessor bp : getBeanPostProcessors()) {
 if (bp instanceof SmartInstantiationAwareBeanPostProcessor) {
 // 如果有 AOP，这里会提前创建代理对象
 exposedObject = ((SmartInstantiationAwareBeanPostProcessor) bp).getEarlyBeanReference(exposedObject, beanName);
 }
 }
 }
 return exposedObject;
}

结论：

第三级缓存存放的 ObjectFactory 提供了一个后悔机制。

如果没发生循环依赖，这个工厂根本不会被调用，AOP 依然在生命周期最后正常进行。
如果发生了循环依赖（B 需要 A），B 会去三级缓存调用 getObject()，强行触发 getEarlyBeanReference，提前把 A 的代理对象创建出来给 B 用。

哪些循环依赖解决不了

Spring 的这套机制不是万能的，以下情况会报错：

构造器注入：
1 2 3 4

@Service public class A { public A(B b) { ... } // 报错 }
原因：Spring 必须先实例化 A，才能放入三级缓存。构造器执行不完，对象就无法实例化，也就没机会放缓存。解决：使用 @Lazy 注解。public A(@Lazy B b)。这会注入一个 B 的代理，真正调用时才去容器找 B。
@Prototype 作用域：
原因：Spring 不会缓存多例（Prototype）对象，每次都 new，自然无法利用缓存机制打破闭环。

Spring Boot 2.6+ 的变化

值得注意的是，从 Spring Boot 2.6.0 开始，默认禁止循环依赖。

如果你的项目中存在循环依赖，启动时会直接报错： Relying upon circular references is discouraged and they are prohibited by default.

官方建议通过重构代码（如提取公共类、使用事件驱动等）来解决。如果非要兼容旧代码，需要在 application.properties 或 yaml 中配置：

1
2
3


spring:
 main:
 allow-circular-references: true

总结

核心手段：Spring 利用 三级缓存 解决了 单例模式 下的 属性注入 循环依赖问题。
原理： 通过“实例化”与“初始化”分离，利用 中间态（半成品） 对象来打破引用环。
三级缓存：
- 一级：最终成品。
- 二级：提前暴露的 Bean（可能是原始的，也可能是代理的），保证多重循环依赖时的引用唯一性。
- 三级：工厂。本质是为了 在 AOP 场景下，能够延迟决策对象的最终形态（是原始对象还是代理对象），并在出现循环依赖时“被迫提前”创建代理对象。

HTTP、Cookie与OAuth认证：API逆向与后端数据的抓取

Fri, 16 Jan 2026 11:40:31 +0000

你是否遇到过这种情况：在网页上看到了一堆有用的数据（比如数据表单、排行榜、或者社交媒体评论），想要把它们保存下来分析，但手动复制粘贴太慢了？

这时候，你需要的是直接与后端服务器对话，从后端抓取数据。

很多人把这叫做“写爬虫”，但更专业的说法是API 逆向或后端数据抓取。今天，我们就抛开复杂的各种自动化浏览器工具（如 Selenium、Playwright），回归本质，聊聊如何像浏览器一样，通过代码直接向服务器索要数据。

我将以获取 PTA 排行榜 ~~(视奸小登进度)~~ 和 反代 Antigravity 的 API 为例。

前端是怎么和后端通信的？

HTTP 协议

浏览器和服务器之间的交流是基于 HTTP 协议（HyperText Transfer Protocol）的。

客户端/浏览器： “我要请求一个 API 获取数据。” —— 请求 (Request)
服务器： “好的，这是您的数据。” —— 响应 (Response)

WebSocket 协议

WebSocket 是一种在单个 TCP 连接上进行全双工通信的协议。它让服务器能够主动向浏览器推送数据。

握手阶段（HTTP）：
- 客户端： “我想升级成 WebSocket 协议。”
- 服务器： “没问题，协议升级成功。”
通信阶段（双向）：
- 客户端： “我发个消息给你。”
- 服务器： “收到，我也传给你个新消息。”
- （连接一直保持，双方可以随时互发数据，不需要重新建立连接）

核心概念

要骗过服务器，让他以为你是浏览器，你需要构造一个完美的请求。一个请求通常包含以下关键部分：

URL (统一资源定位符): 你要去哪里找数据（比如 https://api.example.com/data）。
Method:
- GET: 最常用。意思是“把数据拿给我看”。（比如浏览网页）。
- POST: 意思是“把我的数据提交上去”。（比如登录、提交表单）。
Headers: 这部分最关键！这是你向服务器展示身份的地方。
- Authorizaton: 一般是Bearer <token>，用来验证身份
- User-Agent: 告诉服务器你是谁（是浏览器还是脚本？伪装这个）。
- Referer: 告诉服务器你是从哪个页面跳转过来的（防盗链常用）。
- Content-Type: 告诉服务器你发过去的数据格式（是 JSON 还是表单）。

找到 API 地址——浏览器开发者工具

在你想要找某种数据之前，你需要先当一名侦探。

打开 Chrome 浏览器，按 F12 (或右键 -> 检查)。
点击 Network (网络) 标签页。
点击 Fetch/XHR 过滤器（这一步很重要，这能帮你过滤掉图片、CSS，只看后端返回的数据接口）。
刷新网页。

这时候你会看到一堆请求。逐个点击，查看 Preview 或 Response。当你看到类似

1

{ "name": "张三", "price": 100 }

这种 JSON 格式的数据时，恭喜你，你找到了后端接口

身份验证

很多数据是需要登录才能看到的。但是 HTTP 协议有一个特点：它是无状态的。

服务器不知道刚才请求“登录”的人，和现在请求“个人中心”数据的人是不是同一个。为了解决这个问题，Session 和 Cookie 诞生了。

上文的 PTA 排名接口就是通过 Session 与 Cookie 进行身份验证的。这种方法有一个缺点，你必须定时获取最新的 Cookie 才能顺利从后端拿到数据。

Token 与 OAuth 2.0

现在的网页应用（尤其是前后端分离的 Vue/React 网站）和移动端 App，往往不再使用传统的 Cookie/Session 模式，而是使用 Token。

这里的逻辑是这样的：

你输入账号密码登录。
服务器验证通过，返回一串加密的字符串，叫做 Token（通常是 JWT 格式）。
以后你每次发请求，都要把这个 Token 放在请求头里，通常长这样：
Authorization: Bearer <你的Token字符串>

OAuth 2.0 (开放授权)

你一定见过“使用QQ登录”或“使用 Google 登录”。这就是 OAuth。

它涉及第三方授权。如果你要爬取的数据在通过 OAuth 保护的接口里，流程会比较复杂，你需要模拟整个重定向流程来获取最终的 Access Token。

flowchart TD
 %% 节点定义
 Step1["1. 生成授权 URL
https://accounts.google.com/o/..."]
 Step2["2. 用户在浏览器中登录 Google"]
 Step3["3. 回调到本地服务器
http://localhost:51121/oauth-callback
+ 授权码 (code)"]
 Step4["4. 换取 Token
POST https://oauth2.googleapis.com/token
→ access_token, refresh_token"]
 Step5["5. 获取用户信息
GET /oauth2/v1/userinfo
→ email"]
 Step6["6. 🎯 发现 Project ID
POST /v1internal:loadCodeAssist
→ cloudaicompanionProject"]
 Step7["7. 注册用户 (如需要)
POST /v1internal:onboardUser
→ 轮询直到完成"]
 Step8["8. 调用 Antigravity API
POST /v1internal:streamGenerateContent
Headers: Authorization Bearer token
Body: ( project, model, request... )`"]

 %% 流程连接
 Step1 --> Step2
 Step2 --> Step3
 Step3 --> Step4
 Step4 --> Step5
 Step5 --> Step6
 
 %% 条件分支逻辑
 Step6 -- "如果没有 Project ID" --> Step7
 Step7 --> Step8
 Step6 -- "Project ID 已存在" --> Step8

 %% 样式美化
 style Step6 fill:#e1f5fe,stroke:#01579b,stroke-width:2px
 style Step8 fill:#f3e5f5,stroke:#4a148c,stroke-width:2px

OAuth 2.0 是一个授权框架，允许第三方应用在无需获取用户密码的情况下访问用户资源。

传统方式的问题：

1
2


用户 → 输入密码 → 第三方应用 → 存储密码 → 访问资源
 ❌ 不安全 ❌ 泄露风险 ❌ 权限过大

OAuth 方式：

1
2


用户 → 授权同意 → 获取令牌 → 第三方应用 → 使用令牌访问资源
 ✅ 安全 ✅ 可撤销 ✅ 权限受限

sequenceDiagram
 participant User as 用户
(Owner)
 participant App as 客户端应用
(Your App)
 participant Auth as 授权服务器
(Google)
 
 User->>App: 1. 访问应用
 App->>User: 2. 重定向到授权页面
 User->>Auth: 3. 访问授权页面
 Note over User,Auth: 4. 用户登录并同意授权
 Auth->>User: 5. 返回授权码 (code)
 User->>App: 6. 回调地址 + code
 App->>Auth: 7. code 换 token
 Auth->>App: 8. 返回 token
 App->>Auth: 9. 使用 token 访问 API

核心术语

术语	说明	Antigravity 示例
Client ID	应用标识符	`YOUR_GOOGLE_OAUTH_CLIENT_ID`
Client Secret	应用密钥	`YOUR_GOOGLE_OAUTH_CLIENT_SECRET`
Authorization Endpoint	授权端点	`https://accounts.google.com/o/oauth2/v2/auth`
Token Endpoint	令牌端点	`https://oauth2.googleapis.com/token`
Redirect URI	回调地址	`http://localhost:51121/oauth-callback`
Scope	权限范围	`cloud-platform`, `userinfo. email`
Authorization Code	授权码	`4/0AY0e-g7...` (一次性)
Access Token	访问令牌	`ya29.a0AfH6...` (有效期 1 小时)
Refresh Token	刷新令牌	`1//0gxxx...` (长期有效)

实战

按照你获取的接口，构造请求头:

 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


function buildHeaders(env) {

  const cookie = env.PTA_COOKIE || ''
  const problemSetId = env.PROBLEM_SET_ID || ''
   const xLollipop = env.X_LOLLIPOP || ''

  if (!cookie) {
    throw new Error('缺少必要的环境变量: PTA_COOKIE')
  }

  return {
    'accept': 'application/json;charset=UTF-8',
    'accept-language': 'zh-CN,zh;q=0.9',
    'content-type': 'application/json;charset=UTF-8',
    // 保留 referer，防止盗链验证拒绝访问
    'referer': `https://pintia.cn/problem-sets/${problemSetId}/exam/rankings`,
    'user-agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/142.0.0.0 Safari/537.36',
    //cookie 验证
    'cookie': cookie,
    //这是个安全校验参数
    'x-lollipop': xLollipop,
    'sec-fetch-site': 'same-origin',
    'sec-fetch-mode': 'cors',
    'sec-fetch-dest': 'empty'
  }
}

发送请求：

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


export default {
 async fetch(request, env) {
 const url = new URL(request.url);
 
 // 1. 获取参数
 const page = url.searchParams.get('page') || '0';
 const limit = url.searchParams.get('limit') || '50';
 const problemSetId = url.searchParams.get('setId');

 // 2. 拼接目标 API 地址
 const ptaUrl = `https://pintia.cn/api/problem-sets/${problemSetId}/common-rankings?page=${page}&limit=${limit}`;

 // 3. 发送请求并返回结果
 const ptaResponse = await fetch(ptaUrl, {
 method: 'GET',
 headers: buildHeaders(env) // 必须保留 Header 构建，否则 PTA 会拒绝访问
 });

 return ptaResponse;
 }
}

然后你就能获得 PTA 后端传回的 Body JSON 数据。

但是这个方法有几个缺点：

无法处理过期： 如果 PTA 的服务器判定 Cookie 到期（比如登录失效），它会要求重新登录。你的代码无法自动处理这个过程，只能报错，直到你手动更新 env 里的值。
无法更新 Cookie： 有些服务器会在响应头里返回 Set-Cookie 来更新会话状态。这个代码忽略了 PTA 返回的新 Cookie，始终只用旧的。
x-lollipop ： 这个字段是 PTA 的防爬/安全校验参数，具有很短的时效性。

如果你需要先登录，然后连续访问好几个页面，手动复制 Cookie 很麻烦。Python 的requests.Session() 可以自动帮你管理 Cookie，具备双向更新能力。

或者写一个额外的脚本，模拟登录流程获取新的 Cookie 和 x-lollipop。

OAuth 2.0

以 CLIProxyAPI 这个项目为例：

发现 API 端点

可以用 mitmproxy 抓 Antigragity 的包在 mitmproxy 中寻找这些特征：

OAuth 授权请求
Token 交换请求
API 调用请求

如果无法抓包，可以尝试反编译 JS 或查看配置文件。

这个项目 executor 中的端点定义：

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


const (
 // 多个后备 Base URL (按优先级)
 antigravityBaseURLDaily = "https://daily-cloudcode-pa.googleapis.com"
 antigravitySandboxBaseURLDaily = "https://daily-cloudcode-pa.sandbox.googleapis.com"
 antigravityBaseURLProd = "https://cloudcode-pa.googleapis.com"
 
 // API 路径
 antigravityCountTokensPath = "/v1internal: countTokens"
 antigravityStreamPath = "/v1internal:streamGenerateContent"
 antigravityGeneratePath = "/v1internal: generateContent"
 antigravityModelsPath = "/v1internal:fetchAvailableModels"
 
 // OAuth 配置
 antigravityClientID = "YOUR_GOOGLE_OAUTH_CLIENT_ID"
 antigravityClientSecret = "YOUR_GOOGLE_OAUTH_CLIENT_SECRET"
 defaultAntigravityAgent = "antigravity/1.104.0 darwin/arm64"
 antigravityAuthType = "antigravity"
 refreshSkew = 3000 * time.Second
)

搭建本地 OAuth 回调服务器

OAuth 授权流程中，授权服务器会将授权码通过重定向发送到你指定的 Redirect URI。我们需要一个 HTTP 服务器来接收这个授权码。

 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
38
39
40
41
42
43
44
45
46
47
48


// 回调结果
type callbackResult struct {
 Code string
 Error string
 State string
}

// 启动回调服务器
func startAntigravityCallbackServer(port int) (*http.Server, int, <-chan callbackResult, error) {
 if port <= 0 {
 port = antigravityCallbackPort // 默认 51121
 }
 
 addr := fmt.Sprintf(":%d", port)
 listener, err := net.Listen("tcp", addr)
 if err != nil {
 return nil, 0, nil, err
 }
 
 port = listener.Addr().(*net.TCPAddr).Port
 resultCh := make(chan callbackResult, 1)
 
 mux := http.NewServeMux()
 mux.HandleFunc("/oauth-callback", func(w http.ResponseWriter, r *http.Request) {
 q := r.URL.Query()
 res := callbackResult{
 Code: strings.TrimSpace(q.Get("code")),
 Error: strings.TrimSpace(q. Get("error")),
 State: strings.TrimSpace(q.Get("state")),
 }
 resultCh <- res
 
 if res.Code != "" && res.Error == "" {
 _, _ = w.Write([]byte("<h1>Login successful</h1><p>You can close this window. </p>"))
 } else {
 _, _ = w.Write([]byte("<h1>Login failed</h1><p>Please check the CLI output. </p>"))
 }
 })
 
 srv := &http.Server{Handler: mux}
 go func() {
 if errServe := srv.Serve(listener); errServe != nil && ! strings.Contains(errServe. Error(), "Server closed") {
 log.Warnf("antigravity callback server error: %v", errServe)
 }
 }()
 
 return srv, port, resultCh, nil
}

实现完整 OAuth 流程

构建授权 URL

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


func buildAntigravityAuthURL(redirectURI, state string) string {
 params := url.Values{}
 params.Set("access_type", "offline") // 获取 refresh token
 params.Set("client_id", antigravityClientID)
 params.Set("prompt", "consent") // 强制显示同意页面
 params.Set("redirect_uri", redirectURI)
 params.Set("response_type", "code")
 params.Set("scope", strings.Join(antigravityScopes, " "))
 params.Set("state", state)
 
 return "https://accounts.google.com/o/oauth2/v2/auth?" + params.Encode()
}

完整登录流程

 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
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113


func (AntigravityAuthenticator) Login(ctx context.Context, cfg *config.Config, opts *LoginOptions) (*coreauth.Auth, error) {
 if ctx == nil {
 ctx = context.Background()
 }
 
 httpClient := util.SetProxy(&cfg.SDKConfig, &http.Client{})
 
 // 生成 State (防 CSRF)
 state, err := misc.GenerateRandomState()
 if err != nil {
 return nil, fmt.Errorf("antigravity: failed to generate state: %w", err)
 }
 
 // 启动回调服务器
 srv, port, cbChan, errServer := startAntigravityCallbackServer(antigravityCallbackPort)
 if errServer != nil {
 return nil, fmt. Errorf("antigravity: failed to start callback server: %w", errServer)
 }
 defer func() {
 shutdownCtx, cancel := context. WithTimeout(context.Background(), 2*time.Second)
 defer cancel()
 _ = srv.Shutdown(shutdownCtx)
 }()
 
 // 构建授权 URL
 redirectURI := fmt.Sprintf("http://localhost:%d/oauth-callback", port)
 authURL := buildAntigravityAuthURL(redirectURI, state)
 
 // 打开浏览器
 fmt.Println("Opening browser for antigravity authentication")
 if browser. IsAvailable() {
 if errOpen := browser.OpenURL(authURL); errOpen != nil {
 log.Warnf("Failed to open browser: %v", errOpen)
 fmt.Printf("Visit the following URL:\n%s\n", authURL)
 }
 } else {
 fmt.Printf("Visit the following URL:\n%s\n", authURL)
 }
 
 fmt. Println("Waiting for antigravity authentication callback...")
 
 // 等待回调 (5分钟超时)
 var cbRes callbackResult
 timeoutTimer := time.NewTimer(5 * time.Minute)
 defer timeoutTimer.Stop()
 
 select {
 case res := <-cbChan: 
 cbRes = res
 case <-timeoutTimer.C:
 return nil, fmt. Errorf("antigravity: authentication timed out")
 }
 
 // 验证结果
 if cbRes.Error != "" {
 return nil, fmt.Errorf("antigravity: authentication failed: %s", cbRes.Error)
 }
 if cbRes.State != state {
 return nil, fmt. Errorf("antigravity: invalid state")
 }
 if cbRes.Code == "" {
 return nil, fmt.Errorf("antigravity: missing authorization code")
 }
 
 // 交换授权码获取 Token
 tokenResp, errToken := exchangeAntigravityCode(ctx, cbRes.Code, redirectURI, httpClient)
 if errToken != nil {
 return nil, fmt.Errorf("antigravity: token exchange failed: %w", errToken)
 }
 
 // 获取用户信息
 email := ""
 if tokenResp.AccessToken != "" {
 if info, errInfo := fetchAntigravityUserInfo(ctx, tokenResp.AccessToken, httpClient); errInfo == nil {
 email = strings.TrimSpace(info.Email)
 }
 }
 
 // 获取 Project ID
 // ...
 
 // 构建认证对象
 now := time.Now()
 metadata := map[string]any{
 "type": "antigravity",
 "access_token": tokenResp. AccessToken,
 "refresh_token": tokenResp.RefreshToken,
 "expires_in": tokenResp. ExpiresIn,
 "timestamp": now.UnixMilli(),
 "expired": now.Add(time.Duration(tokenResp.ExpiresIn) * time.Second).Format(time.RFC3339),
 }
 if email != "" {
 metadata["email"] = email
 }
 if projectID != "" {
 metadata["project_id"] = projectID
 }
 
 fileName := sanitizeAntigravityFileName(email)
 
 fmt. Println("Antigravity authentication successful")
 if projectID != "" {
 fmt. Printf("Using GCP project: %s\n", projectID)
 }
 
 return &coreauth.Auth{
 ID: fileName,
 Provider: "antigravity",
 FileName: fileName,
 Label: email,
 Metadata: metadata,
 }, nil
}

Token 交换实现

 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
38
39


func exchangeAntigravityCode(ctx context.Context, code, redirectURI string, httpClient *http.Client) (*antigravityTokenResponse, error) {
 // 构建表单数据
 data := url.Values{}
 data.Set("code", code)
 data.Set("client_id", antigravityClientID)
 data.Set("client_secret", antigravityClientSecret)
 data.Set("redirect_uri", redirectURI)
 data.Set("grant_type", "authorization_code")
 
 // 发送 POST 请求
 req, err := http.NewRequestWithContext(
 ctx,
 http.MethodPost,
 "https://oauth2.googleapis.com/token",
 strings.NewReader(data.Encode()),
 )
 if err != nil {
 return nil, err
 }
 req.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 
 resp, errDo := httpClient.Do(req)
 if errDo != nil {
 return nil, errDo
 }
 defer resp.Body.Close()
 
 // 解析响应
 var token antigravityTokenResponse
 if errDecode := json.NewDecoder(resp.Body).Decode(&token); errDecode != nil {
 return nil, errDecode
 }
 
 if resp.StatusCode < http.StatusOK || resp.StatusCode >= http.StatusMultipleChoices {
 return nil, fmt.Errorf("oauth token exchange failed: status %d", resp.StatusCode)
 }
 
 return &token, nil
}

调用 Antigravity API

构建 API 请求

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69


func (e *AntigravityExecutor) buildRequest(
 ctx context.Context,
 auth *cliproxyauth.Auth,
 token, modelName string,
 payload []byte,
 stream bool,
 alt, baseURL string,
) (*http.Request, error) {
 
 // 选择端点路径
 base := strings.TrimSuffix(baseURL, "/")
 if base == "" {
 base = buildBaseURL(auth)
 }
 
 path := antigravityGeneratePath
 if stream {
 path = antigravityStreamPath
 }
 
 // 构建 URL
 var requestURL strings.Builder
 requestURL.WriteString(base)
 requestURL.WriteString(path)
 
 if stream {
 if alt != "" {
 requestURL. WriteString("?$alt=")
 requestURL.WriteString(url.QueryEscape(alt))
 } else {
 requestURL.WriteString("?alt=sse")
 }
 }
 
 // 提取 Project ID
 // ...
 
 // 转换请求体格式
 payload = geminiToAntigravity(modelName, payload, projectID)
 payload, _ = sjson.SetBytes(payload, "model", modelName)
 
 // 创建 HTTP 请求
 httpReq, err := http.NewRequestWithContext(
 ctx,
 http.MethodPost,
 requestURL.String(),
 bytes.NewReader(payload),
 )
 if err != nil {
 return nil, err
 }
 
 // 设置 Headers
 httpReq.Header.Set("Content-Type", "application/json")
 httpReq.Header.Set("Authorization", "Bearer "+token)
 httpReq.Header.Set("User-Agent", resolveUserAgent(auth))
 
 if stream {
 httpReq.Header.Set("Accept", "text/event-stream")
 } else {
 httpReq.Header.Set("Accept", "application/json")
 }
 
 if host := resolveHost(base); host != "" {
 httpReq.Host = host
 }
 
 return httpReq, nil
}

Token 自动刷新

 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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79


func (e *AntigravityExecutor) refreshToken(ctx context.Context, auth *cliproxyauth.Auth) (*cliproxyauth.Auth, error) {
 if auth == nil {
 return nil, statusErr{code: http.StatusUnauthorized, msg: "missing auth"}
 }
 
 refreshToken := metaStringValue(auth.Metadata, "refresh_token")
 if refreshToken == "" {
 return auth, statusErr{code: http.StatusUnauthorized, msg: "missing refresh token"}
 }
 
 // 构建刷新请求
 form := url.Values{}
 form.Set("client_id", antigravityClientID)
 form.Set("client_secret", antigravityClientSecret)
 form.Set("grant_type", "refresh_token")
 form.Set("refresh_token", refreshToken)
 
 httpReq, errReq := http.NewRequestWithContext(
 ctx,
 http.MethodPost,
 "https://oauth2.googleapis.com/token",
 strings.NewReader(form. Encode()),
 )
 if errReq != nil {
 return auth, errReq
 }
 
 httpReq.Header.Set("Host", "oauth2.googleapis.com")
 httpReq.Header.Set("User-Agent", defaultAntigravityAgent)
 httpReq.Header.Set("Content-Type", "application/x-www-form-urlencoded")
 
 httpClient := newProxyAwareHTTPClient(ctx, e.cfg, auth, 0)
 httpResp, errDo := httpClient.Do(httpReq)
 if errDo != nil {
 return auth, errDo
 }
 defer httpResp.Body.Close()
 
 bodyBytes, errRead := io.ReadAll(httpResp.Body)
 if errRead != nil {
 return auth, errRead
 }
 
 if httpResp.StatusCode < http.StatusOK || httpResp.StatusCode >= http.StatusMultipleChoices {
 return auth, statusErr{code: httpResp.StatusCode, msg: string(bodyBytes)}
 }
 
 // 解析响应
 var tokenResp struct {
 AccessToken string `json:"access_token"`
 RefreshToken string `json:"refresh_token"`
 ExpiresIn int64 `json:"expires_in"`
 TokenType string `json:"token_type"`
 }
 if errUnmarshal := json.Unmarshal(bodyBytes, &tokenResp); errUnmarshal != nil {
 return auth, errUnmarshal
 }
 
 // 更新 auth 对象
 if auth. Metadata == nil {
 auth. Metadata = make(map[string]any)
 }
 
 auth.Metadata["access_token"] = tokenResp. AccessToken
 if tokenResp.RefreshToken != "" {
 auth.Metadata["refresh_token"] = tokenResp.RefreshToken
 }
 auth.Metadata["expires_in"] = tokenResp.ExpiresIn
 
 now := time.Now()
 auth.Metadata["timestamp"] = now.UnixMilli()
 auth.Metadata["expired"] = now.Add(time. Duration(tokenResp.ExpiresIn) * time.Second).Format(time.RFC3339)
 auth.Metadata["type"] = antigravityAuthType
 
 // 确保 project_id 存在
 // ...
 
 return auth, nil
}

其他情况

参数加密与数字签名

你在 Network 里找到了接口，比如 api.com/price?id=100。但是 URL 后面跟了几个参数：&sign=a2f9c8... 或者 &timestamp=169000...&token=...。当你试图把 id 改成 101 时，服务器直接报错“签名无效”。

前端网页里有一段 JS 代码，它会把你的请求参数加上时间戳、随机数，然后用一种算法（比如 MD5、SHA256，或者网站自创的加密逻辑）计算出一个签名。服务器端也会用同样的算法算一遍，如果对不上，就说明这个请求被篡改过，或者不是从浏览器发出的。

这是知乎的签名，没有放在参数里，放在了请求头上。

解决方法：

硬刚（JS 逆向）： 你需要把网页的 JS 代码下载下来，硬着头皮读代码，找到那个加密函数，用 Python 把它重写出来。但是有些 JS 会有混淆，非常掉头发。
投降（使用浏览器自动化）： 放弃直接发 HTTP 请求，改用 Selenium 或 Playwright。这些工具会启动一个真正的 Chrome 浏览器，让浏览器去执行 JS 生成签名，你只负责从页面上拿结果。

JS 动态渲染与混淆

用 GET URL 抓回来的 HTML 源码里，只有一行字： <div id="app"></div> 或者 <script src="main.js"></script>，其他什么内容都没有。

数据不是随 HTML 一起回来的，而是页面加载完后，由 JavaScript 再次发起异步请求加载的。或者这些数据可能不是通过标准的 JSON 接口传输，而是通过 WebSocket，或者直接把数据加密后混淆在 JS 变量里。

解决方法：

普通 API： 继续在 Network 里深挖，肯定有一个 fetch/xhr 请求。
数据混淆在 JS 里： 使用正则表达式在 HTML 源码中提取 JS 变量。

风控验证与指纹识别

Cloudflare 五秒盾或者 CAPTCHA.

脚本底层的 SSL/TLS 握手特征和真正的 Chrome 浏览器是不一样的。Cloudflare 等防火墙能一眼识别出“你不是人，你是脚本，直接拦截返回 403。

解决方法：

针对 TLS 指纹： 使用 curl_cffi 或 tls_client 这种特殊的 Python 库，它们能完美模拟 Chrome 的底层指纹。
针对验证码： 接入打码平台 ~~(金钱是万能的)~~，或者使用机器学习识别。

WebSocket

股票行情、即时聊天、直播弹幕。你在 Network 的 Fetch/XHR 里怎么都找不到数据包。但是点开 Socket 能看见一个升级协议的请求。

它们不用 HTTP 协议，而是用 WebSocket。HTTP 是你问我答的短连接，WebSocket 是一条长长的管道，连接建立后，服务器可以主动不断地推数据给你。

这是 ChatGPT，用的是 Websocket 和后端 API 通信

用对应的websocket库,分析 WebSocket 的握手过程和消息格式（JSON、二进制数据），来获得数据。

Protobuf

Response Header 里写着 content-type: application/x-protobuf。当你打开 Preview 看数据时，全是乱码，根本不是人能看懂的 JSON。

这是 Google 开发的一种二进制序列化格式，比 JSON 更小更快。很多大厂（如 B站的部分接口）为了节省带宽和反爬，会用这个。

上图是 B站的弹幕接口，content-type: application/octet-stream。

这是八位字节流，B 站为了追求极速和极致的性能，把 JSON 压缩成了只有机器能读懂的二进制。

而且，x-client-sign: 就是客户端签名。说明这个请求在发出前，B 站的 JS 脚本对请求参数进行了加密计算，生成了这个签名。如果你手动修改 URL 参数而不更新这个 sign，服务器会直接拒绝。

你需要找到前端定义的 .proto 文件，然后把这些二进制乱码翻译回可读的数据。这也属于逆向工程的一种。

写在最后：

无论是为了拿 PTA 排行榜，还是为了反代 Antigravity 的 AI 接口，“直接找后端要数据” 永远是最优雅的解法。

但是，面对反爬，我们不仅要学会“硬刚”逆向，更要学会在适当的时候“投降”使用浏览器自动化。毕竟，解决问题的代码，才是好代码，效率才是生产力 (笑)。

相关链接: