Home 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())); 
}

其它

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

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

雨崩，下次再见

Sun, 11 Oct 2026 20:34:01 +0800

网上都在说：天堂在左，雨崩在右，我去看看怎么个事。

既然要去，那必须全程徒步，正好当作有氧训练，上科技(骑骡子/坐车)不符合我的原则。

结果是，五天 75km+，累计爬升/下降 5100m+，还好，没有想象中那么累，腿都没酸。先上个轨迹。

Day 1:香格里拉

依旧是熟悉的交通，这次从丽江到香格里拉，路上经过了虎跳峡。

途径虎跳峡

香格里拉不愧是户外人聚集的大本营，刚下车就遇见好多重装徒步佬。

晚上随便逛逛独克宗古城。

世界最大的转经筒，人太多了，进去还得排队，我就懒得去了。

大伙在跳~~神秘广场舞~~。

神秘广场舞

海拔3300m，到我高反海拔阈值了，还好现在没有症状。

尝尝牦牛酸奶和小吃，网红店的口味明显针对大众改良过，少了些纯正当地风味，和当地传统做法有差别，~~感觉像是批发来的常规货，非当地产牦牛和牦牛奶制品~~。

烤菌菇牦牛肉和菌汤，这两个好吃。

店里在跳舞，气氛拉满。

跳舞

晚上睡前测了下血氧，掉到84%，还行吧，只要没出现实质高反症状问题就不大。

这是最后一天早上回到香格里拉站时拍的，竟然也能看见雪山。

Day 2:飞来寺-尼农-上雨崩

半夜里摸黑就爬起来去飞来寺，就是为了赌一把梅里十三峰日照金山。平时早八的班起不来一点，凌晨爬起来看山说去就去。

7:16左右日照金山，我6:20就在飞来寺观景台等了。可惜云层很厚，除了云啥也看不见。放一段延时吧,，看来这次日照金山和我无缘了。

飞来寺延时

直到八点多云散了一点，才能隐约看见卡瓦格博。

去尼农的路上远眺峡谷，还是很壮观的。

将要进尼农

尼农进雨崩的路上。一开始就是一段雷霆大爬升，后面有一段平路，接着又是雷霆大爬升。

尼农进村路上

沿途好多经幡，梅里雪山不愧是藏族的宗教圣地。

爬升，还是爬升，还好我是轻装。

爬升

快到了，已经能看见下雨崩的房子。可惜，看不到左边的缅茨姆(6054)和右边的吉娃仁安(5470.5)。

用时三个小时，马上到上雨崩了。快到上雨崩的这一段，我是真的走到力竭了。这个海拔真走不太快。

这是上雨崩能看见的巴乌八蒙(英雄女儿峰，6000)。可惜可惜，云雾太多了。

Day 3: 冰湖切尼色

今天强度不低，连着走两条线，还好我住的是上雨崩，离起点很近。

早上的的巴乌八蒙。

冰湖徒步起点的白塔。

其实走户外非景区线路有这样一种规律，~~一旦看到“未开发区域严禁进入”的告示牌，基本就证明走对路了~~。

前几天下雨，路上是真的泥，泥深了还滑，不愧是雨崩。

国庆节真是万人攻打雨崩，今年九月西当通车之后人更多了。

一些途径点。

一个半小时爬到笑农垭口，视野豁然开朗，这里就可以看见冰湖了。图里中间偏右上的位置就是冰湖。

这里是卡瓦格博的笑农登山大本营，1991年中日联合登山队17人在此全部遇难的惨烈历史，为这座神山蒙上了一层悲壮而不可侵犯的色彩。后面梅里雪山禁止攀登了，卡瓦格博也成为了一座处女峰。

卡瓦格博攀登历史。

再往后走，视野开阔起来了，景色很不错。

前面就是冰湖了

回头看看来时路。

爬到冰湖线最高点了，冰湖近在咫尺。

我绕着冰湖走了一圈，左上右下。

往冰湖深处走。

冰湖里面

这条河的水是真的急，过河惊险刺激。脚踩在石头上，能明显感受到水的冲击力，脚一滑就会被冲走。我的越野跑鞋全湿了，水是真的冰。

湍急的溪流

过河点

安全下来了，下撤切到尼色森林。都说尼色是原始森林线，很多人到牧场小木屋就折返了，其实去看尼色冰川才是尼色线的精髓。路上捡了个搭子，野生熊远离我。

到尼色牧场了，视野开阔了一些。

上面就是尼色冰川，也是我今天的目的地。左边小山脊的下面就是是 3850 冰洞的位置，只不过冰川表面被冰碛覆盖，远处看起来是黑黑的一片。

这就是冰洞了，还是我第一次零距离走到冰川上。

从尼色牧场到冰洞的一路上我一个人都没遇到，还以为今天只有我一个人，还好在冰洞碰到了几个驴友。

现在气温还没那么低，我不敢进冰洞里面，真怕被埋了。

走近冰洞

回程的森林，这里的森林都是黄绿/浅绿色的，看起来非常嫩，和北方的深绿森林感觉很不一样。

Day 4:下雨崩-神瀑

今天本该是最轻松的一集，溜溜弯的事情。我本来是这么以为的，结果上雨崩到下雨崩的大下坡就给我走热了，短短一公里多就下降200m，太陡了。怪不得这么多人上科技，花60块从下雨崩坐车到上雨崩。

雨崩的经典机位和著名打卡点，都在下雨崩神瀑的起点。

神瀑属于开发成熟的景区路线，一路都是水泥地，沿途有好多经幡和玛尼堆。

爬到神瀑脚下了，远处是神瀑冰川，也能走过去，但是今天淋了一整天小雨，懒得过去了。

神瀑脚下，宗教色彩朝圣氛围很浓烈。

神瀑脚下

神瀑视角下的雨崩村。

Day 5:神湖Plus

如果说昨天是最简单的一集，那今天就是雨崩全线中最难的一天，海拔从 3150 → 3050 → 4650。爬到神湖plus顶，足足1700m的爬升和下降，我从中雨崩出发，还要再多几十上百米。这个海拔上的爬升可没那么简单。

听说，一旦登顶 Plus，就能以最近的视距直面缅茨姆与卡瓦格博，那份震撼无与伦比。

昨天下了一整天雨，一开始就是烂泥地，泥还特别深。往上爬一步，往下滑半步，我真是服了。下坡肯定更滑，赶骡子下来的当地人都穿上冰爪了。

幸运的是，早上往上爬的时候并没有下雨，不用穿硬壳闷着还是很舒服的。

但一到了毫无遮挡的山脊横切路段，大风突然就起来了，过一会还下起了大雪，真是说来就来。横切的坡度陡，路又窄，脚一滑就嗝屁了。

离谱的是这边在刮风下雪，远处却是晴天。

山脊横切

这阵风雪虽然没有哈巴那次的大，但是这雪刮到脸上还是疼，一阵大风来的时候根本走不动道。到了4200营地，风雪更大了，我和路上遇到的驴友都不想上plus了。照现在这天气，上面只会更恶劣。现在营地体感温度已经到了零下，我们把能穿的衣服都穿上了。

4200营地

在这营地扎营过夜的驴友说，他今早上上 Plus 的景色还不错，但是突然起大风下大雪就紧急下撤了。听说他还滑坠了几米。

我和路上遇到的驴友还是决定爬到神湖看看，如果天气太恶劣就不上 Plus 了。这一路的风雪真够大的。

神湖路上的风雪

幸运的是，我们一到神湖，风雪就小了非常多，来都来了，怎么能不去 Plus？神湖线的精华就是 Plus 山顶的风景。

去 Plus 路上俯瞰神湖。

来时路

路上基本没有路迹，我对着大概轨迹找路，只要不走碎石坡就比较安全。

找个路

终于爬上了山脊，离真顶也就几十米了，风景非常壮观。这时候雪也停了，悬崖下面还出了彩虹。

plus山脊上的风景

如果晴天的话，能看到梅里众多雪山。直面缅茨姆。

右边是4700粗卡，左边去真 Plus 顶有一个断崖，得从下面很陡的碎石坡横切上去，非常危险，我们决定不去了，反正海拔也差不了几米。

从左到右依次矗立的神圣雪峰：

缅茨姆（神女峰，6,054ｍ）
吉娃仁安（五佛冠峰，5,470.5）
巴乌八蒙（英雄女儿峰，6,000）
帕巴尼顶九焯（十六尊者峰，5,880）
卡瓦格博（太子峰，6,740）

返程时候天竟然晴了，我是真服了，这就是高海拔变幻莫测的天气吗。不过换个角度想想，风雪交加也是一种体验。

4200营地也有彩虹，这里可以看到右边的尼农峡谷。

下到树林里，考验技术的时候到了。这烂泥地下坡只能滑着走，什么鞋来了都不管用，尤其是某~~黄金大V底~~。我还是摔了个屁墩，气死我了，沾了一裤子泥巴，真是防不胜防。

终于下来了，结算时刻。

沾满泥的鞋

Day 6:尼农出村

这几天转眼就过去了，心里还是很不舍，出村之前看雨崩最后一眼吧。

下雨崩

再见，雨崩！

再见，尼农！

再见，香格里拉！

最后

一旦海拔到了3000+，我的睡眠就会变得很浅，晚上经常醒，应该是因为高海拔的周期性呼吸吧。我天生是易高反体质，这是基因决定的，但这次上到 4650m 一点高反症状都没有，说明海拔适应已经比较充分了。

国庆的雨崩人山人海，西当通车之后更是热闹。但同一个雨崩，也有人迹罕至的一面：从尼色牧场走到冰洞，一路上我一个人都没遇到。水泥路铺到脚下的神瀑线，和基本没有路迹、全靠对着轨迹找路的 Plus 线，体验也完全不一样。

这次雨崩行程比较短暂，虽然没有看到雪山的全貌，但风雪、泥泞、冰川与彩虹交织的这几天，体验也足够充实。

雨崩，下次再见。

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

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 可以改变竞争发生的位置，不能替代“这批库存属于哪个订单”的业务记录。

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

哈巴雪山，止步4500，但我还是很想念那里

Wed, 06 May 2026 20:36:11 +0000

回来以后,我反复翻看登哈巴雪山时候的照片、视频。视频里风雪很大,人走得也很慢,但我看着看着就有种怀念当时的感觉,嘴角不自觉地上扬。

其实这次我并没有登顶,但这并没有让我有太多遗憾。比起"登顶",我更记得那几天的自己非常快乐,也有了再次去挑战哈巴雪山的理由。

想爬上人生第一座雪山

最近一两年,我走过不少徒步路线,高海拔的、低海拔的,困难的、简单的都有,但我还从未体验过在冰川上行走的感觉。

川西虽然有很多所谓的"雪山",但不少存在海拔虚标(比如奥太娜4800米被标成5210米),而且登顶相对简单,体验感并不算强。在我眼里,国内五千米的徒步型雪山,真正能打的只有四姑娘山二峰和哈巴雪山。但二峰没有冰川路段,只有哈巴是全年积雪,并且拥有完整的冰川体系。

为了获得最纯粹的雪山体验,我将哈巴雪山定为了我人生中的第一座雪山。因为五一假期时间充裕,加上五月的雪往往比十月多不少,爬雪山的体验感感会拉满。

我并没有特别强烈的"必须登顶"的执念,在得知大本营被拆除后,以及想起我当时走长穿毕高反的痛苦时,已经有无法登顶的预期了。

Day 1:丽江

我坐成局成段的"AD钙"动集去丽江,直特换桶这件事,虽然有很多人反对,认为票价变贵但并没有提速很不值得,但是"AD钙"的二等座和全列禁烟,乘坐体验确实比以前的绿皮车舒服不少。

途经大理时,窗外的洱海壮观极了。

到达后我直奔丽江古城。网上的攻略都在说丽江古城过于商业化,但是还是值得一去的。

先去忠义市场吃吃吃。

烤饵块,说是糯米做的,~~其实是手抓饼~~。

烤乳扇,还挺好吃,奶味甜甜的。

25一碗的菌菇火腿炒饭,~~其实和普通街边炒饭味道差不多。~~

路上随便照几张。

这是樱花餐厅,丽江古城著名打卡地,可以进去打卡,这有好多多肉植物,晚上配上灯光非常美。

往前走碰到很多人在跳舞,这是什么。

出片胜地们。

这条街有很多心愿卡绑着。

往前走爬一小会就能到丽江之眼~~(忘记是不是叫这个名字了)~~ 可以俯瞰整个古城。

花研古巷头顶有很多伞,也是拍照打卡好地方,应该非常出片吧。

走到对面是丽江古城的水车和非遗牌坊,一般来说这才是古城的正门。

往回走可以去宫门口观景台,视野比之前丽江之眼更开阔,不知道为什么今晚房顶边缘竟然没亮灯。

观景台俯瞰丽江古城夜景视频

回去的路上可以穿过酒吧街,都是清吧,在外面看看就好了。

丽江古城酒吧街清吧夜景视频一

丽江古城酒吧街夜间灯光视频二

丽江古城酒吧街夜景氛围视频三

下来走一会就到木府了,进去要买票,我打了个卡就润了。

走一圈回到忠义市场,正好有点饿了,再吃点烧烤叭。 ~~炸虫就算了。~~

心满意足地回去睡觉。

Day 2:哈巴村

早上顶门去了古城边上的一家咖啡馆,点了一杯拿铁,云南SOE。

市场里的米线,便宜好吃。

清晨的古城非常安静,氛围极好。喝完咖啡,我再次爬上观景台,眺望白天的古城。

白天从观景台俯瞰丽江古城视频

下午和我的队友碰面,都是年轻人哈哈,还有个高三生~~(高三竟然还能出来玩)~~,然后出发去哈巴村。

我们有学生,有刚毕业的,有工作一两年的,反正都很年轻。

这两天玉龙雪山都被云完完全全遮住了。

在虎跳峡打卡。这时候大风就呼呼地刮,我已经想象到后天冲顶的风有多大了。

晚上入住哈巴村客栈,我报的俱乐部客栈应该是住的最高的了,就紧挨着登山起点。从哈巴村登山好像有东西两条路线,我们是在西边线上去的。

晚上向导讲解睡袋、冰镐滑坠制动、怎么穿冰爪,讲完我们就去休息了。

~~登哈巴定妆照:~~

天气预报上,哈巴上的风比珠峰峰顶的风还大。~~五千米的山,八千米的体验。~~

上面就是哈巴雪山,被云遮住了。

Day 3:到大本营

我们早上九点出发,我选择纯徒步上山,淋了一天雨。

外面一直下雨,我的队友都穿上了雨衣。

其实我很不理解,很多人身上穿着始祖鸟,外面还要再套件雨衣,~~(山下始祖鸟,山上凯乐石)~~。这不非常闷汗,穿雨衣是外面被雨打湿,里面被汗打湿,总归都会湿透的。我穿硬壳防雨,漏雨的风险很小,还不像雨衣那么闷。

果然,他们穿雨衣的背包和里面冲锋衣也都湿透了。

路上有人说,宁愿热一点也不想着凉,我觉得,行进中是绝对不能让自己出太多汗的。一开始稍微冷一点,走起来体感刚刚好,才是比较理想的状态。

这烂泥路走的我真难受。

也是有美景的。

我们刻意压住速度,以免高反,用时四个半小时爬上了4000米的营地。到营地后,雨变成了雪,我们的衣服都湿透了,大家围坐在火炉旁烤着湿透的衣服。还好可以烤火。

哈巴雪山4000米营地雨雪天气视频

我说我跑过马拉松,~~向导开玩笑说我只能到4900,哈哈,我也没有嚣张啊,最后其实连4900都没到~~。

我们吃完饭抽签分向导,我的向导帮我调冰爪,分给我一个冰镐,还一直反复叮嘱装备细节,还是很关心客户的。

五六点我们就去休息睡觉了,二人帐比较挤,帐篷是斜的,躺下总会往下溜,我和我的"帐友"都翻来覆去睡不着,前半夜我感觉头痛恶心,有点高反,后半夜好很多。

Day 4:冲顶,以及下撤

凌晨两点起床。

虽然我一晚上没睡觉,但是状态比我预期好很多。我有3600就高反的经历,原本以为我会高反一整夜难受一整夜,结果后半夜感觉还不错。

我们喝了碗粥就出发了。

我一开始压住速度往前走,中间短休,走到了前面。我的向导人很好,愿意开新路,他们在大路的大石板一步一滑,我跟着我向导开的路,走的很舒服。

我一路超人,最后前面只剩下我的向导,我和另外两个队友成了第一梯队。

一开始在林子还好,到了大石板路,那大风夹着雪粒呼呼往我脸上刮,打的疼死我了。

风最大的时候,我甚至连路都走不动,只能把登山杖死死插进雪里,整个人硬抗着,等阵风过去才敢迈步。

越往上走雪越厚,基本上没过膝盖了,最深的地方到腰了,雪厚的地方每走一步都很难。

如果这样还好,节奏保持的不错,我甚至以为我能是今天第一个登顶哈巴的。

但是到了4500铁皮房,现实给了我当头一棒。我们停下来到铁皮房休息,发现没有向导想开路了,都不想上去。开路很费体能,如果有一个向导开,其他人就都跟过去,也不主动去前面开路,所以都不上去开路。

4500米铁皮房附近风雪中的冲顶路段视频

而且越往上雪越厚,向导也觉得危险。

我吃了根胶,胃开始难受了,应该是高反了。

我的向导也劝我下撤,再加上我有点高反,下撤了,我也没有犹豫太久。

下撤了,照两张照片吧。

大雪纷飞。

哈巴雪山下撤途中大雪纷飞视频

超级厚的雪。

哈巴雪山下撤途中深厚积雪视频

昨天这里还是绿绿的,今天下去就变成银色了。

山永远都在哪儿,命只有一条,我还可以下次再来。我一定会回来的。

最后

未曾登顶,但我并不觉得遗憾,反而真正体会到了敬畏自然与量力而行的户外精神。

我记得风雪打在脸上的疼,记得深雪里每一步的艰难,也记得冲在第一梯队时那种兴奋和期待。更重要的是,我记得那几天的自己真的很快乐。

哈巴雪山,感谢你给了我一次如此硬核又快乐的初体验。~~大风下雨下雪起雾,真是体验感满满。~~

山永远都在那里。我们,顶峰再见。

Claude Code 使用方法

Mon, 16 Mar 2026 10:13:25 +0000

关于 Claude Code，官方文档里写得非常详细，请去阅读官方文档。

大多数开发者接触 AI 编码工具，通常还是这几种用法：在聊天窗口里问报错、在编辑器里让它补全几行代码，或者把一段代码贴进去让它解释一下。

AI编程目前可以简单的说，有三个阶段：

网页对话，最早是 ChatGPT 引领全球，将需求或已有代码片段发给gpt，由gpt生成代码后，手动复制粘贴到自己的工程，手动编译调试；
插件工具，有很多工具出来，但最早效果不太理想，直到 cursor 出道，瞬间爆发，代码自动补全非常好用，AI自动识别工程并理解，然后直接修改本地代码，无需用户手动复制粘贴；
Agent托管，在当下 Claude Code、Codex 直接出世，开创全托管编程模式，AI不仅可以编码提交，更能自动测试，产物发布，且配合自定义skill、mcp等，可谓是无所不能（近期出现的龙虾openclaw能做的，它基本上都能），但是否是 VibeCoding 终局，可以拭目以待。

~~其实也可以在龙虾里指挥它用 Claude Code~~

Claude Code 介绍

Claude Code 是一个代理编码工具，可以读取你的代码库、编辑文件、运行命令，并与你的开发工具集成。可在终端、IDE、桌面应用和浏览器中使用。

Anthropic 在官方文档里把它叫做 agentic coding tool。它不只是回答问题的 LLM 客户端，你在项目目录里给出需求，它能拿着你的整个代码仓库去完成这件事，而且是规划开发测试一条龙，有完整的工作流。

无论是 Claude Code 还是 Codex 都支持四种方式：终端CLI、桌面端、插件版、网页版，这里面大家普遍使用最多的是终端 CLI 的方式，毕竟全托管才是未来趋势。

终端版：运行在本地，具有完整功能，无界面消耗，纯命令行操作，可多开并发；
桌面端：与终端版本功能几乎一致，但额外增加了界面的资源损耗（无论是cpu还是内存资源，都是有额外的负担），在多开并发场景下对电脑性能要求更高，但优势在于有界面显示（实际作用不是很明显）；
插件版：嵌入到其他工具(JetBrains、VSCode、Cursor等)，优势在于仍保留现有开发习惯，增加 ClaudeCode 的功能，但注意一旦保留此习惯，那就是势必会削弱AI的存在感，增加人工干预。对于 VibeCoding 来说，这其实是个负担，没有真正的 Agent 托管；
网页版：运行在云端，劣势是无法操作你当前电脑环境，比如修改你本机代码就做不了，但优势在于，可任意设备操作，比如说你的代码本身就是外网可访问（Github仓库），那么你手机可以随时随地的指挥AI干活，完成后自动提交到github。网页版可做任务规划（Plan mode），规划好后，再拉到本地进行实操（会话可以同步到本地）；

与其拿模型能力和其他 AI 工具比，其实差别在它们各自的工作方式。

形态	常见入口	更擅长的事	开发者主要负责什么
聊天式 AI	浏览器 / 对话框	解释问题、给思路、生成示例	自己把方案落到项目里
AI IDE (Cursor、Antigravity)	编辑器	补全、局部修改、边写边问，也能跑小任务	在编辑器里组织上下文和修改
Claude Code / Codex CLI 这类 CLI agent	终端 / 项目目录	读仓库、改多文件、跑命令、验证结果，自动完成一整个需求	描述目标、约束和验收标准

当然，边界也没有这么绝对。AI IDE 这两年也在往 agent 方向更新(比如 Antigravity 也能 VibeCoding，但是效果没有 Claude Code 和 Codex 那么好)，Claude Code 也不只待在 CLI 里。

但实际用下来，区别很明显。如果你只是补一行代码、改个变量名、顺手问一句为什么报错，编辑器里的 AI 已经够用了。一旦任务变成"搞清楚这个模块在干嘛"、“完成一个需求，开发功能”、“跑一遍测试看有没有挂”，Claude Code 这种工具就非常好用。

它做的事情更接近帮你完成一个仓库层面的需求，而不是只回答一个代码片段的问题。

其次 Claude Code 并不是只用于写代码，它也可以做其他事情，可以自动化操作浏览器，可以协助写文档，总结文档等。

Quickstart

环境准备

安装 Git

1
2
3
4
5
6
7
8
9


# windowx
winget install --id Git.Git -e --source winget

# macos
xcode-select --install

# Linux
sudo apt install git
sudo dnf install git-all

验证

1

git --version

安装 Node.js

很多安装命令以及环境运行都依赖nodejs，属于必须安装的系统依赖。官网下载链接：https://nodejs.org/zh-cn/download

1
2
3


node -v # 验证 Node.js 版本
npm -v # 验证 npm 版本
npx -v # 验证 npx 版本

安装 Python

不是必装。

由于 AI 许多技能都是使用py语言编写，所以想要AI有强大的能力，就必须得安装py运行环境。下载地址：https://www.python.org/downloads/

验证：

1

py --version

安装 Claude Code

安装这件事本身不复杂，官方 Quickstart 已经写得比较完整了。

Windows：

1
2
3


irm https://claude.ai/install.ps1 | iex
# 或者
winget install Anthropic.ClaudeCode

macOS / Linux ：

1
2
3


curl -fsSL https://claude.ai/install.sh | bash
# 或
brew install --cask claude-code

或者使用 npm 安装 (官方文档没有，但是能用)：

1

npm install -g @anthropic-ai/claude-code

装好以后，最常见的几种用法大概是这样：

1
2


# 在当前项目里启动交互式会话
claude

Claude Code 命令列表：https://code.claude.com/docs/zh-CN/cli-reference https://code.claude.com/docs/zh-CN/interactive-mode

免费用户由于模型能力较弱，且额度极低，无法达到很好的效果，可按照后续章节提到的方式接其他模型 ~~(这何尝不是一种NTR)~~ 。另外中转站等自定义API则不支持云端执行，只能本地使用，付费用户登录可以云端使用，多端同步。

顺便放一下 Codex 安装

Codex 现在可以免费蹬 gpt-5.4 系列模型，~~后面也会提到怎么薅羊毛~~

1
2
3
4


npm i -g @openai/codex #安装codex

#进入codex开始使用，确认当前工作文件夹以及登陆，然后开始对话即可
codex 

安装 CC Switch

这个工具不是必装，只不过给配置 ClaudeCode 弄了个图形界面而已。

项目地址https://github.com/farion1231/cc-switch/releases/tag/v3.12.2

安装 ccline

这是个 cc 状态栏插件，也不是必装。但是推荐装上，可以看模型和实时上下文token、当前的 git 分支，cc 工作时间等。

项目地址https://github.com/Haleclipse/CCometixLine

图片下面那一行就是 ccline。

使用方法

交互

自然对话：通过claude进入后，可以直接输入自然语言跟AI交互，让AI干活（openclaw能干的，它都能）；
复制粘贴：将外部的长文本粘贴到终端，为避免干扰交互，此时会显示“ [Pasted text #1 +14 lines]”，实际里面就是你所粘贴的文本，回车后会显示实际正文；
提供文件：输入 @ 后，就会出来当前工作目录的文件列表，可以选择，也可以输入文件路径，可继续输入@选择多个文件；
提供图片：复制图片文件后，粘贴进去，就会显示“[Image #2] (↑ to select)”，可粘贴多个图片，如果需要删除，则按“↑”键选择后按Del删除；
终端命令：按"!“后，就是进行终端命令，此时继续输入终端命令即可执行（比如查看目录文件等等），claude不会介入；
管道输入：将一些命令的结果直接给到claude，而无需执行后再复制进行交互。输入 “命令 | claude”，即把命令的结果直接传递给claude。比如让claude看当前文件的所有错误日志，可通过命令查出来再提供给claude，而无需让claude搜索全文，节省token。

多任务并发

虽然AI写代码比人工快了很多，但是执行任务时，因为网络问题，或者工作流比较复杂，AI可能会跑好几个小时完成一个任务。所以使用AI的时候，可以多开几个Claude Code 让他并发执行任务。

多跑几个 CLI 输入 claude 就行。

继续对话

可能不小心关了或者需要继续上次的任务，就需要继续对话。输入 /resume 就行。

压缩上下文

让上下文更短，输入/compact。 Claude Code 也有内置的自动压缩，但是我习惯关掉，与其一直压缩上下文，不如把大需求拆成小需求一个一个做。

清理上下文

上下文过长会影响 AI 的性能，输入 /clear 清理上下文。

Best practices

Claude Code 的 Best practices 文档写的很详细。

让 Claude Code 自动跑测试

能跑测试就跑测试，能看截图就看截图，能用命令输出校验就别只靠看起来没问题。这条几乎是整份 Best practices 里最重要的一条。

大任务先探索，再规划，最后编码

官方并不是说所有事都要先计划一遍；像改 typo、重命名变量这种小事，直接做就行。但只要任务开始涉及多个文件，或者你自己也不确定该怎么下手，先让它读代码、做计划，返工一般会少很多。

按 shift+tab 开启Plan Mode。开了 plan 会比不 plan 写的项目完整的多。

先读代码，比如 read /src/auth and understand how we handle sessions and login. 再规划，比如 I want to add Google OAuth. What files need to change? What's the session flow? Create a plan. 最后实现，implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures. 提交代码 commit 或者提PR，commit with a descriptive message and open a PR.

prompt 里要给它具体上下文

光说修 bug还是太空了。更有效的方式是把症状、可能相关的目录、不能动的部分、参考文件或者测试要求一起说清楚。Claude Code 能自己找东西，但前提是你得先把问题范围画出来。

管理上下文

官方文档对 context 讲得很直白：上下文一长，模型能力会下降。

所以不相关的任务别硬塞在一个会话里，必要时直接 /clear。长期稳定的规则放到 CLAUDE.md 里，像测试命令、代码风格、仓库约束这种，交给它记住会更省事。

编写 CLAUDE.md

这就像是项目的全局 prompt，claude code 执行任务会先读这个文件。

可以输入 /init 初始化 CLAUDE.md。

另外，CLAUDE.md 也不是越长越好。官方建议其实很克制：CLAUDE.md 文件没有必需的格式，但保持简短和易读。只写那些 Claude 靠读代码也推不出来、但又会反复影响结果的东西。再细一点、只在特定场景下才需要的知识，更适合放到 skills 或 hooks 里，而不是把一个文件越堆越长。

打断

Claude code 有时候会跑偏，在它跑偏的时候及时按 ESC 打断

进阶用法

接入 MCP

接入 Skills

Claude Skills 是一套允许Claude模型通过包含指令、脚本和资源的模块化文件夹来提升特定任务执行能力的“外挂”系统。它采用“渐进式加载”技术，在需要时按需调用，减少了上下文Token占用，能实现复杂工作流自动化（如自动化代码审查、数据处理），显著提升企业或个人用户在专业领域的输出质量与效率。

skills 可以简单的理解成，在告诉AI于什么场景就做什么事情，让AI知道自己有什么额外的功能，怎么去使用这些功能，比如claude无法直接读取pdf文件，那么就可以安装一个pdf skill，这样ai就可以读取pdf文件了（其实自定义命令也是skills的一种）。

制作自己的 Skills

手写md文件就行，也可以装 claude code 插件让它帮你创建skills。

官方教程

目录和文件格式：

1
2
3
4
5
6
7


my-skill/
├── SKILL.md # 主要说明（必需）
├── template.md # Claude 要填写的模板
├── examples/
│ └── sample.md # 显示预期格式的示例输出
└── scripts/
 └── validate.sh # Claude 可以执行的脚本

自定义 Hooks

官方教程

钩子的作用可以简单的理解成AOP切面操作或者说是绑定事件，当出现什么事情的时候，让AI执行指定任务。

比如说，当 ai 干完活后的通知，在控制台不明显，导致容易被忽略，那么就可以让ai增加系统通知，或者每次保存文件前执行格式化代码，再或者执行命令是对 rm-rf 进行拦截。开发网站功能完成后，让ai继续使用插件自行测试功能，让 ai 24小时马不停蹄的干，配合多任务执行，完美。

SubAgents

官方教程

简单的说就是，给AI设定不同的角色，给与不同的上下文、约定、权限，让不同AI有不一样的预埋规则，各自注重点不同。

白嫖指南

很多团队需要用 Claude Code，需要接入企业 API，个人或者小团队使用直接跳到 接入第三方API 部分即可。

先说 provider 和部署方式。按照官方文档，Claude Code 不只支持直接使用 Anthropic 账号，也支持第三方API和通过 Anthropic Console、Amazon Bedrock、Google Vertex AI 和 Microsoft Foundry 来接入。

对个人用户来说，直接登录官方账号通常最省事；到了公司环境，网络代理、统一鉴权、成本统计这些问题就会浮出来，这时往往会用到企业代理或者 LLM gateway。

官方文档里能看到的相关环境变量，常见的像这些：

1
2
3
4
5
6


HTTP_PROXY
HTTPS_PROXY
ANTHROPIC_BASE_URL
ANTHROPIC_BEDROCK_BASE_URL
ANTHROPIC_VERTEX_BASE_URL
ANTHROPIC_FOUNDRY_BASE_URL

如果是通过 Bedrock、Vertex 或 Foundry 接入，实际配置时通常还会配合对应 provider 的启用和认证变量一起使用。对个人来说，这部分未必用得上，但到了团队场景，它就不只是能不能连上，而是和权限、计费、网络策略一起考虑的事了。

白嫖部分接入自己的/第三方 Provider

Claude Code 还支持接入自己的或者第三方(中转站) 的 API。你可以接入任意兼容 Anthropic 接口的 API。

目前写代码能力第一梯队 ~~(版本T0)~~ 是claude-opus-4-6和gpt-5.4。

gemini-3.1-pro-preview属于 T1 级别。

GLM-5，minimax-m2.7，composer-2 之类的是 T2 往后了，其他模型看看就得了。

那怎么白嫖 T0模型呢？截至至2026/3/24，能用顶级模型最好的办法就是反代 Codex。

Codex 对免费 openai 账户提供了一点 gpt-5.4 和 gpt-5.3-codex 的额度，~~可以使用注册机注册几十上百个号，这样就可以爽用了~~。

GPT Team 也可以低价白嫖，需要域名邮箱，验证卡之类的，~~理论上零成本，但是奥特曼会时不时杀掉你的号，嘻嘻。~~

反代 Antigravity 使用 Claude Opus 4.6 会被封号，如果 Google 一天一封，~~你一天准备一个号进家庭组也是可以的~~。

具体反代API项目常用的有两个，按照项目文档使用即可，拿到 API 地址和 key 放到 claude code 配置文件就 ~~可以尽情白嫖啦~~。

推荐个人使用：CLIProxyAPI 推荐商业使用(中转站)：Sub2api

以 Windows 为例，进入C:\Users\你的用户名\.claude\settings.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


{
  "env": {
    "ANTHROPIC_BASE_URL": "你的中转站URL",
    "ANTHROPIC_AUTH_TOKEN": "你的中转站APIKEY",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "模型名",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "模型名",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "模型名"
  }, 
  "effortLevel": "high"
}

注意 HAIKU 模型一定要用快速小模型。

接入第三方中转站需要加以下四个配置，屏蔽掉claude code 发的无意义请求头。

1
2
3
4
5
6
7
8


{
 "env": {
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "DISABLE_BUG_COMMAND": "1",
    "DISABLE_ERROR_REPORTING": "1",
    "DISABLE_TELEMETRY": "1"
  }
}

分享一下我的配置：

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


{

  "env": {
    "ANTHROPIC_AUTH_TOKEN": "******",
    "ANTHROPIC_BASE_URL": "https://your.domain",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "gpt-5.4-mini",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "gpt-5.4(xhigh)",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "gpt-5.4(xhigh)",
    "ANTHROPIC_REASONING_MODEL": "gpt-5.4(xhigh)",
    "CLAUDE_CODE_ATTRIBUTION_HEADER": "0",
    "DISABLE_BUG_COMMAND": "1",
    "DISABLE_ERROR_REPORTING": "1",
    "DISABLE_TELEMETRY": "1"
  },
  "model": "opus[1m]",
  "effortLevel": "high",
  "autoUpdatesChannel": "latest"
}

插件系统

这件事真正有意思的地方不在“多了一个命令”，而在于 Claude Code 的工作边界开始从本地仓库往外扩。它不只是读代码，还能把设计稿、工单、错误监控、数据库信息一起拉进同一条任务链里。

插件则是另一个层面的扩展。Claude Code 的插件系统可以把 skills、agents、hooks、MCP server、LSP server 这些能力打包到一起，更适合团队共享，而不是每个人都零散配一遍。官方现在也有插件发现页和 marketplace，常见的管理入口是 /plugin 和 /reload-plugins。

以下插件输入 /plugin 就能找到，都在 Anthropic 官方 plugin market 里面

frontend-design

这是 Anthropic 开发的用于打造具有独特设计的生产级前端的插件。可以生成精良的代码，避免千篇一律的AI美学，~~千篇一律的蓝紫色UI~~。让 Claude Code 写前端页面的时候这个 skill 自动开启。

superpowers

让 Claude Code 进行头脑风暴，也就是开发之前先进行规划，会问你很多问题确定开发的方向，也会制定开发的规范：测试必须在实现之前失败、要求在进行任何修复之前进行根本原因调查、在开始编码之前完善需求。

做大项目推荐使用，这个插件的Skills定义了完整的工作流：需求分析，和你对话确认需求，subagent 创建分支写代码，冒烟测试，commit 提 PR或者合并回主分支。

~~只不过做任务出奇的慢，烧Token也是出奇的多。~~

context7

这是 Upstash 开发的用于实时文档查找的 MCP Server，可以将特定版本的文档和代码示例从源代码库提取到 LLM 环境中。

在开发对接第三方API查文档非常好用，防止AI用已经过时的信息或者乱写。

只需在需要查看最新文档的任何提示中添加“use context7”即可。例如：“创建一个 Next.js 中间件，用于检查 cookie 中是否存在有效的 JWT。use context7”或“配置一个 Cloudflare Worker 脚本来缓存 JSON API 响应。use context7”。还可以使用“use library /supabase/supabase for API and docs”来指定具体的库。

playwright

用于AI控制你的浏览器，进行浏览器自动化，比如说测试网页界面，自动协助操作等等，让claude执行命令自动安装。

claude-md-management

这个插件是让 Claude Code 扫描代码库中所有 CLAUDE.md 文件，并根据质量标准（命令、架构、注意事项、简洁性）对其进行评估，然后生成包含分数和等级的详细质量报告。之后，它会根据发现的不足之处提出有针对性的改进建议。

说出“审核我的 CLAUDE.md 文件”或“检查我的 CLAUDE.md 文件是否为最新版本”即可触发审核功能。/revise-claude-md在完成一次高效的工作后运行此功能，可以获取新的见解。插件会将建议的更改以差异的形式显示，并且只有在批准后才会应用这些更改。

最后

所以如果只是把 Claude Code 理解成另一个聊天窗口或者AI IDE，其实有点低估它。它更像是一个能进项目、能调用工具、也能自我验证的编码 Agent。

使用 Claude Code 并不复杂，你只要会安装、启动、对话即可，其余都是进阶功能，适合定制自己的工作流和开发环境。

后续用熟 Claude Code 之后，就会尝试提效，提高代码生成质量，优化自动化流程，这时候就是捣鼓 Skills，Hooks这类功能的时候。

~~Token就是生产力，这也是你担心获取大量Token的时候。~~

However, Claude Code当然不是所有场景都比 AI IDE 更顺。局部补全、短平快的小修改，编辑器里的体验还是更自然。但一旦任务开始跨文件、跨命令、还需要验收，Claude Code 和普通聊天式 AI 的差别就会很明显。

Claude Code 真正有意思的地方，不只是会不会写代码，而是让 AI 从回答代码问题这件事，往参与工程流程更靠近了一步，~~初级程序员距离失业也靠近了一大步。~~

Uptime Kuma，颜值与实力并存的开源监控神器

Mon, 02 Feb 2026 20:20:24 +0000

市面上有许多成熟的监控服务，比如 UptimeRobot 或 StatusCake，但它们往往存在免费版限制（如监控频率低、数量少）或者界面老旧、功能收费等问题。至于 Zabbix 或 Prometheus，对于轻量级需求来说，配置又显得过于厚重。

那么就得请出一款开源、免费、界面现代且功能强大的自托管监控工具——Uptime Kuma。

什么是 Uptime Kuma？

Uptime Kuma 是一个由开发者 Louis Lam 编写的自托管监控工具。它的定位非常清晰：做一个像 UptimeRobot 样子的自托管监控工具，但要在 UI 和体验上更进一步。

它基于 Vue 3 和 Node.js 构建，拥有极具现代感的响应式界面（Material Design 风格），并且支持中文。

它可以用来监控服务，设置定时任务(自动签到)，平台保活，消息推送等等。

为什么选择 Uptime Kuma？

Uptime Kuma 凭借以下几个核心优势成为了我的首选：

极其丰富的监控类型

不仅仅是简单的 Ping 或 HTTP 请求，它支持多种协议：

HTTP(s)：支持关键字检测、重定向检查。
TCP / Ping：基础连通性测试。
DNS：检查域名解析。
Push：类似于“心跳检测”，适合监控内网脚本是否按时运行。
Docker 容器：可以直接监控 Docker 容器的运行状态。
数据库：支持 MySQL/MariaDB, PostgreSQL, Redis 等。

强大的通知渠道

监控到了故障，通知不到位也是白搭。Uptime Kuma 集成了 90+ 种通知方式，几乎覆盖了所有主流平台：

国内常用：Telegram, 企业微信, 钉钉, 飞书, 阿里云短信, ServerChan。
国际常用：Discord, Slack, Microsoft Teams, Pushover, Signal。
通用：Email (SMTP), Webhook。

这意味着，当你的网站挂掉的那一秒，你的手机就能立刻收到弹窗警告。

漂亮的自定义状态页

你想给用户展示当前系统的运行状况吗？Uptime Kuma 内置了状态页生成功能。你可以将特定的监控项映射到状态页，绑定自定义域名，并配置 SSL。它生成的页面简洁美观，完全可以替代付费的 Status Page 服务。

极致的轻量与易用

资源占用低：跑在一个 1核 512M 的 VPS 上都绰绰有余，我跑在了 GCP 的 2C1G 的 VPS 上。
部署简单：基于 Docker，一行命令即可启动。
界面友好：全图形化操作，无需编写复杂的 YAML 配置文件。

上手指南

最简单的部署方式是使用 Docker。

部署安装

打开你的终端，运行以下命令（创建一个卷以持久化数据）：

1
2
3
4
5


# 创建一个卷
docker volume create uptime-kuma

# 启动容器
docker run -d --restart=always -p 3001:3001 -v uptime-kuma:/app/data --name uptime-kuma louislam/uptime-kuma:1

如果你更喜欢使用 docker-compose.yml，可以使用以下配置：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


version: '3.3'

services:
 uptime-kuma:
 image: louislam/uptime-kuma:1
 container_name: uptime-kuma
 volumes:
 - ./uptime-kuma-data:/app/data
 ports:
 - 3001:3001 # <Host Port>:<Container Port>
 restart: always

初始化设置

在浏览器中访问 http://你的IP:3001 或者 Nginx 的反代地址。
第一次访问会要求你创建一个管理员账号和密码。

登录后，你就可以看到空空如也的仪表盘了。

添加第一个监控

点击左上角的 “+ Add New Monitor”。
Monitor Type选择 HTTP(s)。
Friendly Name填入你的网站名（例如：我的博客）。
URL 填入网址。
Heartbeat：默认 60秒，你可以设置得更短，比如 20秒（这是免费版 UptimeRobot 做不到的）。
点击右下角的 “保存”。

配置通知

点击右上方的头像 -> “设置” -> “通知”。
点击 “设置通知”。
选择你喜欢的类型（例如 Telegram 或钉钉），填入相应的 Token 或 Webhook URL。
点击 “测试”，确认收到消息后保存。

对外显示

点击右上方的 Status Pages -> “设置” -> “通知”。
点击 “+ New Status Page”。
Name 填你 Status Page 显示的标题名字
Slug 填你 Status Page 的路径，默认是/status/default

点击 Edit Status Page
点 + Add Group 添加分组，点 Add a monitor 添加监控服务

进阶玩法

反向代理：为了安全，建议使用 Nginx 或 Caddy 对 3001 端口进行反向代理，并配置 SSL 证书，通过 HTTPS 访问面板。SSL 证书可以用 certbot 获取。

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


server {
 listen 443 ssl;
 server_name your_domain;

 ssl_certificate /etc/letsencrypt/live/inst.falnsakura.top/fullchain.pem;
 ssl_certificate_key /etc/letsencrypt/live/inst.falnsakura.top/privkey.pem;

 location / {
 proxy_pass http://127.0.0.1:3001;
 
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;

 proxy_http_version 1.1;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 }
}

双机热备：有些极客会买两台便宜的 VPS 互相同步监控，防止“监控服务器本身挂了”的尴尬情况。
维护模式：当你需要对服务器进行例行维护时，可以开启维护模式，暂时抑制报警通知。
自动签到：抓取你需要签到网站的签到接口，加上 Bearer Token 或者 Cookie 之类的凭证。
网站保活：比如防止 Hugging Face Space 休眠，定期 curl 你的网站就好了，建议一天一次就够了。
接入谷歌分析：在左侧填入你的 Google Analytics ID 即可
自定义样式：用 CSS 注入的方式

总结

Uptime Kuma 完美诠释了什么是优秀的开源软件：解决痛点、界面美观、简单易用且完全免费。如果你正在寻找一个能够掌控自己服务状态或者自动签到、服务保活的工具，Uptime Kuma 绝对是目前最好的选择之一。

赶紧去给你的服务器装上这个“贴身保镖”吧！

相关链接：

GitHub 项目地址: https://github.com/louislam/uptime-kuma
如何抓接口地址: https://www.falnsakura.top/2026/01/get-backend-apis/

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 场景下，能够延迟决策对象的最终形态（是原始对象还是代理对象），并在出现循环依赖时“被迫提前”创建代理对象。

拒绝 if-else：基于 DDD 与状态机的订单业务

Tue, 20 Jan 2026 10:56:07 +0000

作为一名后端开发者，你一定看过这样的代码：比如你要写一个订单业务，在 OrderService 里写了一堆 if-else 来判断订单能不能发货、能不能退款。随着业务越来越复杂，这些 if 就像面条一样缠在一起，改一个地方崩三个地方，这种代码非常不健康。

我们要用 DDD（领域驱动设计） 的思想，配合 状态机模式，让你的业务代码更健壮。

背景

假如你有个订单业务，订单有以下几种状态：

CREATED: 待支付
PAID: 已下单，待接单
ACCPETED: 已接单
DELIVERED: 已送出
COMPLETED: 已完成
CANCELLED: 已取消
REFUNDED: 已退款

用户事件：

支付： 把 CREATED 变成 PAID。
收货： 把 DELIVERED 变成 COMPLETED，或者把 CREATED 变成 CANCELLED 。
退款： 把某一状态变成 REFUNDED。

以前我们是怎么写的：

这是典型的“三层架构”写法。

Order.java (实体类，只有Getter/Setter)

1
2
3
4
5
6
7
8


// 这就是所谓的“贫血模型”，它只是数据的搬运工，没有脑子
@Data
public class Order {

 private Long id;
 private String status; // 状态直接存字符串或者常量数字
 // public static final Integer PENDING_PAYMENT = 1;...
}

OrderServiceImpl.java (Service层的业务逻辑)

 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


@Service
public class OrderService {
 @Autowired private OrderMapper orderMapper;

 // 处理支付逻辑
 public void pay(Long orderId) {
 Order order = orderMapper.selectById(orderId);
 
 // 痛点：大量的状态判断逻辑散落在 Service 层
 if (!"CREATED".equals(order.getStatus())) {
 throw new BusinessException("只有待支付的订单才能支付！");
 }
 
 // 痛点：直接操作 Set 方法，任何代码都能随意改状态，很不安全
 order.setStatus("PAID"); 
 orderMapper.updateById(order);
 }

 // 处理收货逻辑
 public void receive(Long orderId) {
 Order order = orderMapper.selectById(orderId);
 
 // 又是重复的判断逻辑...
 if ("CREATED".equals(order.getStatus())) {
 throw new RuntimeException("还没付钱呢，不能收货！");
 }
 if ("COMPLETED".equals(order.getStatus())) {
 throw new RuntimeException("已经收过货了！");
 }

 order.setStatus("COMPLETED");
 orderMapper.updateById(order);
 }
}

这种写法的问题：

逻辑分散：判断能不能支付、能不能收货的逻辑都在 Service 里，如果你的系统里有 5 个地方都能触发支付，你就要写 5 遍 if 判断。
不安全：谁都可以调用 order.setStatus("随便啥")，数据很容易搞乱。如果不小心在“已取消”状态执行了“发货”，系统就会崩溃或产生脏数据。
难以维护和扩展：如果需要新增一种订单状态，而这种状态夹在现有状态中间，需要大改业务代码和判断逻辑。

为了解决这个问题，我们需要引入两个核心工具：领域驱动设计 (DDD) 和 状态机 (State Machine)。

DDD 与状态机

在优化代码前，先明白几个术语：

名词	术语	通俗解释
聚合根	Aggregate Root	就是那个实体类（这里是 `Order`）。在 DDD 里，主角要有“脑子”，逻辑要写在它里面，而不是写在 Service 里。
状态	State	订单现在的样子，比如“待支付”。
事件	Event	触发变化的动作，比如“用户支付”。
流转	Transition	从 A 状态变成 B 状态的过程。
卫语句	Guard	门卫。在变状态前检查一下合不合法（比如：没付钱不能发货）。

DDD 聚合根

在 DDD 中，聚合根 (Aggregate Root) 是业务逻辑的最小边界。它必须保证其内部数据的完整性和一致性。订单 (Order) 就是一个典型的聚合根。在 DDD 看来，状态的变更不应该是 Service 层手动 setStatus，而应该是聚合根对外部事件的响应。

状态机

状态机（State Machine） 是一个经典概念，它由三个核心要素组成：

State：实体所处的状况（如：待支付、已支付、已发货）。
Event：触发状态流转的动作（如：支付、发货、收货）。
Transition：从一个状态变为另一个状态的过程，通常伴随着 Guard 和Action。

DDD 与状态机的结合点

在 DDD 中，聚合根 负责维护数据的一致性。状态是聚合根最核心的属性之一。

将状态机引入 DDD，主要遵循以下原则：

状态即语言：状态枚举（Enum）和触发事件（Event）应该是领域专家和开发者共同认可的通用语言。
显式流转：禁止直接 setStatus。状态的改变必须通过触发“事件”来完成。
逻辑内聚：状态机配置（谁能流转到谁）应该属于领域层，而不是应用层。

实战架构设计

一个简单的电商订单生命周期：

stateDiagram-v2
 [*] --> CREATED: 下单
 
 CREATED --> PAID: 支付
 CREATED --> CANCELED: 取消
 
 PAID --> DILIVERED: 发货
 PAID --> REFUNDING: 申请退款
 
 DILIVERED --> COMPLETED: 签收
 DILIVERED --> REFUNDING: 拒收/退货
 
 REFUNDING --> REFUNDED: 退款成功
 REFUNDING --> PAID: 退款失败/撤销
 
 COMPLETED --> [*]
 CANCELED --> [*]
 REFUNDED --> [*]

我们要实现的流程：

sequenceDiagram
 participant User as 用户(Controller)
 participant Service as OrderService
 participant Domain as Order(聚合根)
 participant FSM as OrderStateMachine(规则表)
 participant DB as 数据库

 User->>Service: 请求支付 (pay)
 Service->>DB: 查订单 (status=CREATED)
 DB-->>Service: 返回对象
 
 Service->>Domain: order.sendEvent(PAY)
 
 Note over Domain, FSM: 重点业务
 Domain->>FSM: 问: CREATED + PAY = ?
 FSM-->>Domain: 答: 允许，新状态是 PAID
 
 Domain->>Domain: 更新自身 status = PAID
 
 Service->>DB: 保存订单

我们的目标是：把逻辑从 Service 挪进 Order 类里，并用一张“配置表”来管理状态变化。

第一步：定义枚举

不要用字符串 “PAID”，要用枚举。

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


// 状态枚举
public enum OrderStatus {
 CREATED, 
 PENDING_ORDER, 
 ACCPETED, 
 DELIVERED, 
 COMPLETED, 
 CANCELLED, 
 REFUNDED
}

// 事件枚举
public enum OrderEvent {
 PAY, // 支付
 RECEIVE, // 收货
 REFUND //退款
}

第二步：设计状态机

我们要告诉程序：在什么状态下，发生什么事件，变成什么新状态。现有的状态机框架有 Spring Statemachine 和阿里的 Cola StateMachine 等。但是，我们现在不用复杂的框架，写一个简单的静态映射表。

 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


public class OrderStateMachine {
 // 映射表：当前状态 -> (发生事件 -> 下一个状态)
 private static final Map<OrderStatus, Map<OrderEvent, OrderStatus>> TRANSITIONS = new HashMap<>();

 static {
 // 规则1：如果是 CREATED 状态，发生了 PAY 事件，变成 PAID
 addTransition(OrderStatus.CREATED, OrderEvent.PAY, OrderStatus.PAID);
 // 规则2：如果是 DILIVERED 状态，发生了 RECEIVE 事件，变成 COMPLETED
 addTransition(OrderStatus.PAID, OrderEvent.RECEIVE, OrderStatus.COMPLETED);
 // 规则3：如果是 PAID/DELIVERED 状态，发生了 REFUND 事件，变成 REFUNDED
 addTransition(OrderStatus.PAID, OrderEvent.REFUND, OrderStatus.REFUNDED);
 }

 private static void addTransition(OrderStatus current, OrderEvent event, OrderStatus next) {
 TRANSITIONS.computeIfAbsent(current, k -> new HashMap<>()).put(event, next);
 }

 // 核心方法：获取下一个状态
 public static OrderStatus getNextStatus(OrderStatus current, OrderEvent event) {
 Map<OrderEvent, OrderStatus> eventMap = TRANSITIONS.get(current);
 if (eventMap == null || !eventMap.containsKey(event)) {
 // 如果表里没配这条规则，说明是不合法的操作
 throw new RuntimeException("当前状态 " + current + " 不能进行 " + event + " 操作");
 }
 return eventMap.get(event);
 }
}

第三步：改造 Order 类

现在的 Order 不再只是 getters/setters 了，它有了行为。

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


// 一个 DDD 风格的聚合根
@Data
public class Order {
 private Long id;
 private OrderStatus status;

 public Order() {
 this.status = OrderStatus.CREATED;
 }

 // 对外不提供 setStatus，只提供业务
 // 外部只能告诉 Order 发生了什么事件
 public void sendEvent(OrderEvent event) {
 // 1. 问状态机：下一个状态是什么（包含校验逻辑）
 OrderStatus nextStatus = OrderStateMachine.getNextStatus(this.status, event);
 
 // 2. 只有这里能修改状态，保证业务安全
 this.status = nextStatus;
 
 System.out.println("订单 " + id + " 状态流转成功：" + event + " -> " + this.status);
 }
}

第四步：新版的 Service（变得极简）

Service 不再负责复杂的判断，它只负责从数据库查到聚合根，然后触发事件。

 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


@Service
@Transactional
public class OrderService {
 @Autowired private OrderMapper orderMapper;

 public void pay(Long orderId) {
 // 1. 取出聚合根
 Order order = orderMapper.selectById(orderId);
 
 // 2. 触发事件（逻辑都在 Order 和 状态机里，Service 不用操心 if-else）
 order.sendEvent(OrderEvent.PAY);
 
 // 3. 保存状态
 orderMapper.updateById(order);
 }

 public void receive(Long orderId) {
 Order order = orderMapper.selectById(orderId);
 
 // 只要调用同一个方法，传入不同事件即可
 order.sendEvent(OrderEvent.RECEIVE);
 
 orderMapper.updateById(order);
 }
 
 public void refund(Long orderId) {
	 Order order = orderMapper.selectById(orderId);
 
 // 只要调用同一个方法，传入不同事件即可
 order.sendEvent(OrderEvent.REFUND);
 
 orderMapper.updateById(order);
 }
}

与原来对比

特性	旧写法	DDD + 状态机
代码位置	逻辑散落在 Service 的各个方法里	逻辑内聚在 `Order` 类和 `StateMachine` 配置里
可读性	满屏的 `if (status == 1)`	清晰的 `Map` 配置表，一眼看出业务流程
扩展性	加个新状态要改好几个 Service 方法	只需要在配置表里加一行代码
安全性	任意代码都能 `setStatus`，容易改错	禁止 `setStatus`，只能通过合法事件驱动
复用性	别的 Service 要用还得重写判断逻辑	直接复用 `Order` 类的方法

这种模式的挑战

在分布式环境下，状态机面临以下挑战：

状态竞争 (并发)

当两个线程同时尝试更新同一个订单的状态时（如用户点击取消的同时，支付回调到达）的时候:

在数据库上加乐观锁，增加 version 字段。

1

UPDATE orders SET status = 'PAID', version = version + 1 WHERE id = 1 AND version = 5;

幂等性

如果支付回调由于网络原因重试(支付回调来了两次)，状态机已经处于 PAID 了，再次收到 PAY_SUCCESS 的时候：

状态机引擎应具备“自动过滤”功能。如果当前状态已是目标状态，直接返回成功，不触发 Action。

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


public void handlePaymentCallback(Long orderId) {
 Order order = orderMapper.selectById(orderId);
 
 // 幂等性检查：如果已经是 PAID，直接返回成功，不做任何副作用
 if (order.getStatus() == OrderStatus.PAID) {
 log.info("订单 {} 已经是支付状态，忽略重复回调", orderId);
 return; // 直接结束，视为成功
 }

 // 正常的流转逻辑...
 order.sendEvent(OrderEvent.PAY);
 // ...
}

副作用与持久化

状态转换成功了，但发送消息队列失败的时候：

1
2
3
4
5
6
7
8
9


// 错误示范
@Transactional
public void pay(Long orderId) {
 updateDbStatus(orderId, "PAID"); // 1. 数据库事务未提交
 mqProducer.send("OrderPaid"); // 2. 发送MQ消息
 // 3. 如果这里代码报错了，或者数据库提交失败了：
 // 结果：数据库回滚（还是待支付），但 MQ 发出去了（消费者以为支付了）。
 // 或者反过来：数据库成功，MQ 发送因为网络超时失败。
}

解决方案：本地消息表： 把“发消息”这个动作，变成“往数据库插一条记录”。这样数据库的状态更新和消息记录就在同一个事务里，失败就都回滚。

建表：local_event_table (id, event_content, status)。 Service 层：

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


@Transactional(rollbackFor = Exception.class)
public void pay(Long orderId) {
 Order order = orderMapper.selectById(orderId);
 
 // 1. 更新订单状态
 int rows = orderMapper.updateStatusSafe(orderId, OrderStatus.PAID, order.getVersion());
 if (rows == 0) throw new OptimisticLockException("...");

 // 2. 不要直接发 MQ，而是保存一条“待发送消息”到数据库
 LocalEvent event = new LocalEvent();
 event.setTopic("OrderPaid");
 event.setContent(JSON.toJSONString(order));
 event.setStatus("PENDING");
 eventMapper.insert(event); 
 
} // 3. 事务提交

异步线程：
写一个定时任务（或者监听器），专门去查 local_event_table 里 PENDING 的消息，发送给 MQ，发送成功后再把表里的状态改为 SENT。

可靠的状态变更

sequenceDiagram
 participant User
 participant Service
 participant DB as 数据库(Order表 & Event表)
 participant Worker as 异步补偿任务
 participant MQ

 User->>Service: 触发动作
 
 rect rgb(240, 240, 240)
 Note right of Service: 开启数据库事务
 Service->>DB: UPDATE order SET status='PAID'...
 Service->>DB: INSERT INTO local_event...
 Service-->>User: 返回成功
 Note right of Service: 提交事务
 end
 
 par 异步处理
 Worker->>DB: 轮询 status='PENDING' 的消息
 Worker->>MQ: 发送消息
 alt 发送成功
 Worker->>DB: UPDATE local_event SET status='SENT'
 else 发送失败
 Worker->>DB: 保持 PENDING，下次重试
 end
 end

复杂条件判断

不是所有 CREATED 都能变 PAID。
业务规则：只有金额 > 0 且库存充足 才能支付。如果把这些逻辑写死在 if-else 里，Service 又乱了。

使用策略接口注入。在状态机定义里，加入一个 Condition 接口。

 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


// 1. 定义条件接口
@FunctionalInterface
public interface TransitionCondition<T> {
 boolean isSatisfied(T context);
}

// 2. 状态机配置类增强
public class OrderStateMachine {
 // 存储：状态 -> (事件 -> {目标状态, 校验逻辑})
 static class Transition {
 OrderStatus target;
 TransitionCondition<Order> condition;
 }
 
 // 配置流转
 static {
 // 只有库存足够，才能从 CREATED -> PAID
 addTransition(OrderStatus.CREATED, OrderEvent.PAY, OrderStatus.PAID, 
 (order) -> order.getAmount() > 0 && InventoryService.check(order.getId())
 );
 }
}

// 3. 调用
public void pay(Order order) {
 // 状态机内部会自动执行 isSatisfied()
 // 如果返回 false，抛出异常 "条件不满足：库存不足"
 order.sendEvent(OrderEvent.PAY); 
}

最后

不要过度设计。如果你的状态只有 2 个（开/关），或者订单只有几个状态，用简单的 if-else 也没问题。当状态很多且流转复杂时，状态机才是神器。
试着把业务逻辑写进实体类里，而不是全部堆在 Service 里，这是写 DDD 的第一步。
持久化。数据库里存的还是简单的字符串或数字（比如 status="PAID"），状态机只是内存里的逻辑校验器，不需要把状态机存到数据库里。

通过这种方式，你的代码不再是面条，冗长难以维护和扩展，而是一台精密的仪器，每个部件各司其职。这就是架构设计的精妙之处。

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 接口，“直接找后端要数据” 永远是最优雅的解法。

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

相关链接:

使用 Cloudflare Tunnel 给 Huggingface Space 自定义域名

Thu, 15 Jan 2026 15:08:57 +0000

Huggingface 其实也是个大善人，有免费的 2c 16g 的 space 让你免费用。

美中不足的是普通版不能自定义域名，那么就用 cf tunnel 给他反代一下。

Cloudflare Workers 也可以反代抱抱脸空间，但是会占你访问额度，也有CPU时间限制。。。如果你需要 Websocket 也有点麻烦。。。

更新

⚠️ Warning

仅仅打包成镜像仍然有被封空间的危险！

可以套一层 nginx ，在7890端口伪装静态页面 main.conf

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


server {
 listen 7860;
 listen [::]:7860;
 server_name _;

 location / {
 root /usr/share/nginx/html;
 index index.html;
 }

 location /health {
 return 200 'OK';
 add_header Content-Type text/plain;
 }
}

再启用 ssl 反代 ssl.conf.template

 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


server {
 listen 443 ssl;
 listen [::]:443 ssl;

 server_name ARGO_DOMAIN_PLACEHOLDER;
 ssl_certificate /app/cert.pem;
 ssl_certificate_key /app/cert.key;
 ssl_session_timeout 1d;
 ssl_session_cache shared:SSL:10m;
 ssl_protocols TLSv1.2 TLSv1.3;

 underscores_in_headers on;

 # WebSocket 支持
 location /ws {
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header Upgrade $http_upgrade;
 proxy_set_header Connection "upgrade";
 proxy_set_header X-Real-IP $http_cf_connecting_ip;
 proxy_read_timeout 86400;
 proxy_send_timeout 86400;
 proxy_buffering off;
 proxy_pass http://127.0.0.1:8080;
 }

 # API 和主服务
 location / {
 proxy_http_version 1.1;
 proxy_set_header Host $host;
 proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
 proxy_set_header X-Forwarded-Proto $scheme;
 proxy_read_timeout 300s;
 proxy_send_timeout 300s;
 proxy_buffering off;
 proxy_pass http://127.0.0.1:8080;
 }
}

加上这个启动脚本，把容器日志输出在hf的容器日志里

 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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189


#!/bin/sh
set -e

# =========================
# 环境变量（隐蔽名称）
# =========================
ARGO_DOMAIN=${DD_DM:-""}
ARGO_AUTH=${DD_DD:-""}

# =========================
# 日志函数
# =========================
log_info() { echo "[INFO] $(date '+%Y-%m-%d %H:%M:%S') $1"; }
log_ok() { echo "[OK] $(date '+%Y-%m-%d %H:%M:%S') $1"; }
log_error() { echo "[ERROR] $(date '+%Y-%m-%d %H:%M:%S') $1"; }
log_warn() { echo "[WARN] $(date '+%Y-%m-%d %H:%M:%S') $1"; }

# =========================
# 辅助函数
# =========================
wait_for_port() {
 local port=$1
 local timeout=$2
 for i in $(seq 1 $timeout); do
 if curl -s http://127.0.0.1:$port > /dev/null 2>&1; then
 return 0
 fi
 sleep 1
 done
 return 1
}

start_webui() {
 log_info "正在启动 Open WebUI..."
 cd /app/backend
 
 # 核心修改：使用 tee 将日志同时输出到文件和控制台，确保 HF 能看到日志
 # 使用 stdbuf -oL 减少缓冲，让日志实时显示
 stdbuf -oL nohup ./start.sh > /tmp/webui.log 2>&1 &
 
}

# 实时读取日志文件的后台进程（确保日志能显示在 HF 控制台）
tail_logs() {
 touch /tmp/webui.log
 tail -f /tmp/webui.log &
}

echo "===== Application Startup at $(date '+%Y-%m-%d %H:%M:%S') ====="

# =========================
# 步骤 1: 启动 Nginx (健康检查)
# =========================
echo "=========================================="
echo " 步骤 1: 启动 Nginx (端口 7860)"
echo "=========================================="

mkdir -p /var/www/html
nginx

sleep 2

if curl -s http://127.0.0.1:7860/health > /dev/null 2>&1; then
 log_ok "Nginx 端口 7860 已就绪"
else
 log_error "Nginx 端口 7860 检查失败"
fi

# =========================
# 步骤 2: 启动 Open WebUI
# =========================
echo "=========================================="
echo " 步骤 2: 启动 Open WebUI"
echo "=========================================="

# 检查目录是否存在
if [ ! -d "/app/backend" ]; then
 log_error "/app/backend 目录不存在"
 exit 1
fi

cd /app/backend

# 检查启动脚本是否存在
if [ ! -f "./start.sh" ]; then
 log_error "start.sh 不存在"
 exit 1
fi

# 启动 Open WebUI

tail_logs

# 启动 WebUI
PORT=8080 HOST=0.0.0.0 start_webui

if wait_for_port 8080 60; then
 log_ok "OWU 已启动"
else
 log_error "Open WebUI 启动超时或失败，最后 20 行日志："
 tail -n 20 /tmp/webui.log
 # 这里不退出 exit 1，而是进入循环尝试挽救
fi

# =========================
# 步骤 3: 生成 SSL 证书
# =========================
if [ -n "$ARGO_DOMAIN" ]; then
 echo "=========================================="
 echo " 步骤 3: 生成 SSL 证书"
 echo "=========================================="
 
 log_info "生成证书: $ARGO_DOMAIN"
 
 mkdir -p /app
 
 openssl genrsa -out /app/cert.key 2048 2>/dev/null
 openssl req -new -subj "/CN=$ARGO_DOMAIN" -key /app/cert.key -out /app/cert.csr 2>/dev/null
 openssl x509 -req -days 36500 -in /app/cert.csr -signkey /app/cert.key -out /app/cert.pem 2>/dev/null
 
 sed "s/ARGO_DOMAIN_PLACEHOLDER/$ARGO_DOMAIN/g" /etc/nginx/ssl.conf.template > /etc/nginx/conf.d/ssl.conf
 
 nginx -s reload
 sleep 1
 log_ok "证书生成完成，443 端口已启用"
fi

# =========================
# 步骤 4: 启动隧道（进程名伪装）
# =========================
if [ -n "$ARGO_AUTH" ]; then
 echo "=========================================="
 echo " 步骤 4: 启动辅助服务"
 echo "=========================================="
 
 # 使用重命名后的二进制
 /usr/local/bin/dd-dd tunnel --no-autoupdate run --protocol http2 --token "$ARGO_AUTH" > /tmp/tunnel.log 2>&1 &
 
 sleep 5
 
 if pgrep -f "dd-dd" >/dev/null; then
 log_ok "辅助服务启动成功"
 else
 log_error "辅助服务启动失败"
 cat /tmp/tunnel.log
 fi
fi

# =========================
# 完成
# =========================
echo "=========================================="
echo " 所有服务已启动"
echo "=========================================="
[ -n "$ARGO_DOMAIN" ] && log_ok "访问地址: https://$ARGO_DOMAIN"
log_info "HTTP: http://localhost:7860"
log_info "WebUI: http://localhost:8080"

# =========================
# 健康检查循环
# =========================
while true; do
 
 # 检查隧道
 if [ -n "$ARGO_AUTH" ] && ! pgrep -f "dd-dd" >/dev/null; then
 log_warn "隧道进程丢失，正在重启..."
 /usr/local/bin/dd-dd tunnel --no-autoupdate run --protocol http2 --token "$ARGO_AUTH" > /tmp/tunnel.log 2>&1 &
 fi
 
 # 检查 Nginx
 if ! pgrep -x "nginx" >/dev/null; then
 log_warn "Nginx 进程丢失，正在重启..."
 nginx
 fi

 if ! curl -s http://127.0.0.1:8080/health > /dev/null 2>&1; then
 sleep 5
 if ! curl -s http://127.0.0.1:8080/health > /dev/null 2>&1; then
 log_warn "OWU (端口 8080) 无响应，尝试重启..."
 pkill -f "uvicorn" || true
 pkill -f "start.sh" || true
 
 # 重启
 PORT=8080 HOST=0.0.0.0 start_webui
 fi
 fi
 
 sleep 60
done

打包好的镜像

 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


FROM ghcr.io/open-webui/open-webui:main

USER root

# 安装 Nginx 和其他工具
RUN apt-get update && apt-get install -y \
 nginx \
 openssl \
 curl \
 procps \
 && rm -rf /var/lib/apt/lists/*

# 复制 cloudflared（伪装名称）
COPY --from=cloudflare/cloudflared:latest /usr/local/bin/cloudflared /usr/local/bin/dd-dd

# Nginx 配置
COPY main.conf /etc/nginx/conf.d/main.conf
RUN rm -f /etc/nginx/conf.d/default.conf && \
 rm -rf /etc/nginx/sites-enabled/* && \
 rm -rf /etc/nginx/sites-available/*
COPY ssl.conf.template /etc/nginx/ssl.conf.template

# 复制自定义文件
COPY entrypoint.sh /entrypoint.sh
COPY index.html /usr/share/nginx/html/index.html

# 设置权限
RUN chmod +x /entrypoint.sh && \
 sed -i 's/\r$//' /entrypoint.sh

EXPOSE 8080

ENV DD_DM="" \
 DD_DD="" \
 PORT=8080 \
 HOST=0.0.0.0

CMD ["/entrypoint.sh"]

前置条件

一个 Cloudflare 账号
一个已托管在 Cloudflare 的域名
一个 dockerhub 账号
一个 github 账号
一个运行中的 Huggingface Space

开始

创建 Cloudflare Tunnel

登录 Cloudflare Dashboard
选择你的域名
进入 Zero Trust > Networks > Tunnels
点击 Create a tunnel
选择 Cloudflared，输入隧道名称（如 huggingface-space）
点击 Save tunnel

配置 Tunnel

创建完成后，你会看到安装 cloudflared 的命令，但我们不需要安装，因为我们只用它做反向代理。

复制那个 ey开头的 base64 token 备用。

配置公共主机名

在 Tunnel 详情页面，切换到 Public Hostname 标签
点击 Add a public hostname
填写配置：具体配置看你的容器，需要监听什么端口，什么协议，以open-webui为例
- Subdomain: 输入子域名（如 chat）
- Domain: 选择你的域名
- Type: 选择 HTTP
- URL: 由于和 openwebui 镜像打包在一起，填localhost:7860
点击 Save hostname

配置保存后，Cloudflare 会自动创建 DNS 记录并配置 Tunnel。通常在几分钟内即可生效。

使用 Github Actions 自动构建镜像

直接在 hf space 的 Dockerfile 里把 cloudflared 镜像是不行的，你的 space 会被秒封(pause)。于是，你必须预先打包好镜像，把想要部署的镜像和 cloudflared 打包在一起。

你可以直接 Fork 我的仓库。

以下是自己操作的流程。新建一个仓库，仓库根目录创建Dockerfile。这里以 open-webui 为例，镜像、端口和依赖安装自己改一下。

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


FROM {你想部署的镜像}

USER root
RUN apt-get update && apt-get install -y --no-install-recommends curl ca-certificates && rm -rf /var/lib/apt/lists/*

COPY --from=cloudflare/cloudflared:latest /usr/local/bin/cloudflared /usr/local/bin/cloudflared

ENV PORT=7860
ENV HOME=/tmp

EXPOSE 7860

CMD cloudflared tunnel --no-autoupdate run --token ${ARGO_AUTH} & bash start.sh

创建 Github Actions Workflow 在仓库 .github/workflows下创建 docker-build.yml 写入以下配置：

 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


name: Build and Push Open-WebUI-Argo

on:
 push:
 branches: [ "main" ]
 workflow_dispatch:

env:
 DOCKER_IMAGE: {你的用户名}/{你的镜像名}

jobs:
 build:
 runs-on: ubuntu-latest
 steps:
 - name: Checkout code
 uses: actions/checkout@v4

 - name: Set up QEMU
 uses: docker/setup-qemu-action@v3

 - name: Set up Docker Buildx
 uses: docker/setup-buildx-action@v3

 - name: Login to Docker Hub
 uses: docker/login-action@v3
 with:
 username: ${{ secrets.DOCKERHUB_USERNAME }}
 password: ${{ secrets.DOCKERHUB_TOKEN }}

 - name: Build and push
 uses: docker/build-push-action@v5
 with:
 context: .
 push: true
 tags: |
 ${{ env.DOCKER_IMAGE }}:latest
 ${{ env.DOCKER_IMAGE }}:${{ github.sha }}
 cache-from: type=gha
 cache-to: type=gha,mode=max

把镜像推送到 Dockerhub

去 Dockerhub 的 Account Settings > Settings > Personal Access Tokens 拿到你账号的token。

你想推到 GHCR 也可以的，记得把你的 GHCR 镜像设为公开

创建新 token，填好名称，例如github actions。类型至少选 Read & Write。 token只会展示一次，复制形如 dcr_xxx 的 token 备用。

添加 Github 仓库环境变量

进入你仓库的 Settings > Secrets and variables 如果让你创建环境，随便创建一个就行。填入如下两个 secrets：

注意：必须是 secrets 而不是 variables

DOCKERHUB_TOKEN，填入你上一步获得的 token
DOCKERHUB_USERNAME，填入你dockerhub的用户名

如果是 非public 的 GHCR 镜像仓库，你需要填的是 github user token，workflows配置文件也需要修改推送和登录部分

等待 Actions 跑完成功即可

修改你的 HF Space

把你 Huggingface Space 仓库的 Dockerfile 修改为拉你自己打包的新镜像。还是以我的open-webui为例

1

FROM docker.io/你的用户名/镜像名:标签

如果是 GCHR 仓库：

1

FROM ghcr.io/你的用户名/镜像名:标签

在你的 hf space 环境变量添加一个 secret 变量，填入你的 cloudflared token。 ARGO_AUTH=eyJxxxxx

等待生效

启动你的 HF Space，去你的 cf tunnel 查看状态，为正常 tunnel 就没问题

访问你配置的域名（如 https://demo.yourdomain.com），就能看到你的 Huggingface Space 了！

添加访问控制

你可以使用 Cloudflare Access 为你的 Space 添加身份验证：

在 Tunnel 的 Public Hostname 设置中
找到 Access 部分
创建访问策略，可以设置：
- 邮箱白名单
- GitHub OAuth
- Google OAuth
- auth0, keyloack…

自定义缓存规则

既然用了 cf，那就不得不说他的 CDN 服务了，静态资源多的可以试试。在 Cloudflare Rules 中可以为你的域名设置：

缓存策略
防火墙规则
速率限制

其他

如果使用 HTTPS ，一般都是 nginx 反代的，记得在 tunnel 设置里关闭 TLS 验证，开启 **HTTP/2**访问。

gRPC 的话要去你的域名设置页面开启 通过gRPC访问你的域名。

通过 Cloudflare Tunnel (Cloudflare Workers也是可以的)，我们可以轻松为 Huggingface Space 绑定自定义域名，无需任何服务器，完全免费。这个方法同样适用于其他需要反向代理的服务。

关于优选加速访问，cf tunnel 可以通过 SaaS 优选哦。

🚨 Caution

谨慎使用，千万不要在 Space 明文使用 cf tunnel，否则你的 space 会喜提秒封。

🚨 Caution

也不要在 Huggingface Space 部署 AList，也会秒封。

相关链接：

52.63km，10万步：我用双脚丈量了峨眉山的全程

Wed, 14 Jan 2026 10:20:47 +0000

“别人问我为什么要走完全程？我说，山就在那里，而这只有区区五十公里。”

挑战的开始

起因其实很偶然。在逛“两步路”APP时，无意间发现了一条峨眉山的“VIP路线”（懂的都懂，逃票进山路）。

因为这条路线的特殊性，下山时无法购买景区大巴车票。我当时想都没想，心一横：既然坐不了车，那就干脆走下去。五十多公里，在地图上看起来也就是一截指头的长度，没什么大不了的。

毕竟我都能跑 42.195 的马拉松。

后来的事实证明：确实“没什么大不了的”。

身体的勋章

在开始叙述细节前，先晒出这枚属于我的勋章：

总里程： 52.63 公里
总步数： 100,000+ 步
累计爬升： 4137 米
耗时： 21h
消耗热量： 7832 kcal


52.63 km 轨迹图	4137 m 累计爬升

爬升的虐点：永无止境的石阶

一开始遇到了拦路泼猴，好在被人用弹弓赶走了。

很多人说“九十九道拐”是极限，但对我来说，那只是热身。真正让人崩溃的是洗象池前后的那段路。真是永无止境的爬升。

石阶似乎永远没有尽头，每走几步就要停下来大口喘气，肺部像是在拉风箱。最后我甚至都想用雪山步一步一步往上挪了。 那种感觉就像是： 你以为快到终点了，结果一看轨迹，你才走了十分之一。

下雪了，还好我有冲锋衣。冲锋衣虽然防水，但在那种高湿度环境下，外面是雪水，里面是排不出去的冷凝水，整个人湿得透透的。

这是我第二次爬峨眉山，第一次是坐车下去的。邪门的是，两次到金顶都是大雾加下雪。我这运气，真是“好”得让人想骂人。😡

因为上去得太早，天还没亮，金顶的寒风像刀子一样。最后，我不得不躲进厕所里蹭点暖气避风。

一出来真是冻死了，什么万佛顶，什么日出云海，通通随风去吧，下次再来吧。

下山是幸福的…呃？

清晨下去的路上全是雾凇，爬上来的时候是晚上，根本看不见。这么一看，真美啊。

下去整体上是轻松的，但几乎遇不到和我一样走下山的。

这段是平路，走在没什么人的小路上还挺惬意。

一开始下去路上的爬坡根本爬不动，下台阶时间长了肌肉竟然恢复了。我下去的时候，路人经常问我：“这个坡还有多远？"，“还要走多久能到雷洞坪啊？” 这段路正是我挪上来的那段。路人脸上挂满了痛苦面具，哈哈。

我只能一边安慰他们“快了快了”，一边想：加油吧，真正的绝望还在后面呢。

万年寺那条路的石阶上结满了暗冰，真是防不胜防。结果摔了好几个屁墩，疼死了😭。

更气人的是，下山路居然还有不少爬升坡度，每上一级台阶都在挑战我所剩无几的耐心。最后，终于变成了平整的沥青路下坡，我干脆跑起来了，爽！跑到了报国寺，也就是大多数人徒步的起点(我的起点是高铁站)。

写在最后

21小时，52公里。
峨眉山的台阶很硬，但我的意志和肌肉更硬。
下次还来吗？
——万佛顶还没去呢，日出云海没看到呢，总得找个机会三刷吧。

使用 Cloudflare R2 零成本搭建个人图床

Tue, 13 Jan 2026 10:37:05 +0000

在写博客或者维护网站时，图片的托管一直是个让人头疼的问题。放在本地会增加 Git 仓库体积，使用公共图床又担心随时“跑路”。今天介绍如何利用 Cloudflare R2 搭建一个高速、稳定且几乎免费的个人图床。

另外，对象存储在折腾 serverless 的时候也是不可或缺的。

什么是对象存储？

在开始之前，我们需要了解什么是对象存储。

简单来说，对象存储是一种专门为大规模非结构化数据（如图片、视频、备份文件等）设计的存储架构。与传统电脑上的“层级文件系统”（文件夹嵌套）不同，对象存储将数据作为“对象”进行管理：

对象（Object）：包含数据本身、元数据（Metadata）和全局唯一的标识符（ID）。
桶（Bucket）：存放对象的容器。
特性：它具有极高的扩展性和可靠性，通过 API 或 URL 直接访问，非常适合作为网站的静态资源存储。

常见的对象存储服务有亚马逊的 AWS S3、阿里云的 OSS 和腾讯云的 COS。

什么是 S3 API ?

AWS S3 (Simple Storage Service) 的 API 是目前云存储行业的事实标准。绝大多数的对象存储服务（包括 Cloudflare R2、阿里云 OSS、腾讯云 COS、MinIO）都完全兼容 S3 API。

理解了 S3 API 的用法，你就可以一套代码通用所有主流云存储。

准备工作

在使用 API 之前，你必须拥有：

Access Key ID (访问密钥 ID)
Secret Access Key (私有访问密钥)
Endpoint URL (终结点，如果是 AWS 官方则不需要专门指定，如果是 R2 或自建 Minio 则必须指定)
Region (区域，如 us-east-1，R2 可以填 auto)

为什么选择 Cloudflare R2 ？

Cloudflare R2 是兼容 S3 标准的对象存储服务，它最大的杀手锏是：免收出口流量费（Zero Egress Fees）。

传统的云厂商（如 AWS 或阿里云）通常会对图片加载产生的流量收费，如果你的博客访问量大，这笔费用会很可观。而 Cloudflare R2：

1. 每月前 10GB 存储免费。

2. 每月 A 类操作（写）100 万次免费，B 类操作（读）1000 万次免费。

3. 完全没有流量费。

对于个人来说，这几乎就是永久免费。

搭建步骤

1. 开启 Cloudflare R2

如果 API 调用或者存储容量超了 Free Tier 会扣钱的

我用的是工行星座卡（免年费😋），注册一个非国区 PayPal 也可以，能绑银联卡。

2. 创建 Bucket（桶）

点击 Create bucket，起一个名字（例如 my-blog-images），区域选择 Automatic 即可。

3. 配置公开访问

R2 默认不允许公开访问，只能通过 API 访问。若想搭建图床之类的并能直接访问，需要配置有域名。

在 Bucket 详情页中，选择 Settings 选项卡：

找到 Custom Domain。
点击 Add，输入你的子域名（例如 img.yourdomain.com）。
这样你就可以通过自己的域名访问图片了，且自带 CDN 加速。

如果你的域名没有放在 Cloudflare 托管，可以将域名迁移到 Cloudflare，或者使用 Cloudflare Workers 中转。如果你只想搬子域名（例如 img.abc.com），可以在你原来的服务商那里，把 img 这个子域名的 NS 记录 指向 Cloudflare 分配给你的 NS 地址。这叫“DNS 委派”。如果在 Cloudflare ，cf 会自动帮你添加 DNS记录。

4. 获取 API 密钥

回到 R2 主页，点击右侧的 Manage ：

点击 Create User API token。

权限选择 Object Read & Write。
保存好生成的 Access Key ID 和 Secret Access Key，以及 Endpoint。

配置 CORS 策略

**CORS (Cross-Origin Resource Sharing) 是一种安全机制。简单来说，由于浏览器的“同源策略”，默认情况下，域名 A 的网页不允许去读域名 B 的资源。

如果你在 blog.com 上引用了 img.com 的图片，并且你需要通过脚本（比如 Canvas 处理、图片懒加载插件等）去操作这张图片，就必须在 img.com（即 R2 存储桶）上明确允许 blog.com 的访问。

1. 进入设置界面

登录 Cloudflare 控制台。
点击左侧 R2，选择你创建好的 Bucket（存储桶）。
点击上方的 Settings 选项卡。
向下滚动找到 CORS Policy 部分，点击 Add CORS policy。

2. 填写配置文件

在弹出的编辑框中，复制并粘贴以下 JSON 代码：

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


[
  {
    "AllowedOrigins": [
      "*"
    ],
    "AllowedMethods": [
      "GET",
      "PUT",
      "POST",
      "DELETE",
      "HEAD"
    ],
    "AllowedHeaders": [
      "*"
    ],
    "ExposeHeaders": [],
    "MaxAgeSeconds": 3000
  }
]

配合 PicGo 实现自动化上传

手动上传图片很麻烦，我们推荐使用 PicGo 客户端：

在 PicGo 中安装 s3 插件。

配置插件参数：

应用密钥 ID：你的 Access Key ID。
应用密钥：你的 Secret Access Key。
桶名：my-blog-images。
自定义节点：你的 R2 Endpoint（去掉末尾的桶名部分）。
自定义域名：你绑定的自定义域名（如 https://img.yourdomain.com）。

可以配合图片压缩食用，节省存储空间，不会牺牲太多图片质量

把 PicGo 放到 Obsidian 实现图片无缝上传

安装 Image auto upload 插件

配置插件

配置完成后，在写 md 的时候把图片复制进来，图片会自动上传到 R2。再也不用操心传 md 还得传图片的问题了😋。

配置 Cloudflare 优选域名

如果嫌国内访问太慢，可以用 Cloudflare Workers 反代来配置 Cloudflare 优选域名。

1
2
3
4
5
6
7


export default {
  async fetch(request) {
    const url = new URL(request.url);
    url.hostname = 'img.yourdomain.com';
    return fetch(url, request);
  },
};

再添加 Workers 路由，把 DNS 记录里的 CNAME 指向的域名改成 Cloudflare 优选域名即可。

优选前，只解析到了两个 IP

优选后

搭建完成后，你就可以访问 https://img.yourdomain.com/bucketname/path 访问你的图片了。

Home on Fallensakura715's Blog

订单幂等与支付回调改造

原项目的问题

设计下单幂等请求

流程

建表

代码实现

SQL 和 DAO

业务代码

Controller

长事务的缺点

支付幂等

建表

代码实现

notify 通知接收

订单校验

其它

雨崩，下次再见

Day 1:香格里拉

Day 2:飞来寺-尼农-上雨崩

Day 3: 冰湖切尼色

Day 4:下雨崩-神瀑

Day 5:神湖Plus

Day 6:尼农出村

最后

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

原项目的问题

为什么要预占库存

库存原子更新

库存预占幂等

库存预占与释放

超时库存释放

代码示例

预占库存

支付后确认

取消后释放

超时库存释放

超时重试可靠性

没有解决分布式事务

行锁性能瓶颈

哈巴雪山，止步4500，但我还是很想念那里

想爬上人生第一座雪山

Day 1:丽江

Day 2:哈巴村

Day 3:到大本营

Day 4:冲顶,以及下撤

最后

Claude Code 使用方法

Claude Code 介绍

Quickstart

环境准备

安装 Git

安装 Node.js

安装 Python

安装 Claude Code

顺便放一下 Codex 安装

安装 CC Switch

安装 ccline

使用方法

交互

多任务并发

继续对话

压缩上下文

清理上下文

Best practices

让 Claude Code 自动跑测试

大任务先探索，再规划，最后编码

prompt 里要给它具体上下文

管理上下文

编写 CLAUDE.md

打断

进阶用法

接入 MCP

接入 Skills

制作自己的 Skills

自定义 Hooks

SubAgents

白嫖指南

白嫖部分 接入自己的/第三方 Provider

插件系统

白嫖部分接入自己的/第三方 Provider