Pasule Blog

微服务架构设计原理与最佳实践

Sat, 15 Nov 2025 00:00:00 GMT

微服务架构设计原理与最佳实践#

🚀 本文将带你深入了解

微服务架构的核心理念和优势

从单体应用向微服务的渐进式迁移策略

Spring Cloud生态系统完整解决方案

分布式系统设计的关键考量点

生产环境下的微服务治理实践

📚 目录概览#

什么是微服务架构
微服务vs单体应用对比
微服务设计原则
技术栈选型指南
实战案例：电商系统微服务化
常见陷阱与解决方案

🎯 什么是微服务架构#

微服务架构是一种分布式系统设计方法，它将单一应用程序开发为一套小型服务，每个服务运行在自己的进程中，并使用轻量级机制（通常是HTTP资源API）进行通信。

核心特征#

graph TB A[微服务架构] --> B[服务独立部署] A --> C[业务功能单一] A --> D[去中心化治理] A --> E[故障隔离] A --> F[技术多样性] B --> B1[独立发布周期] B --> B2[独立扩缩容] C --> C1[单一职责原则] C --> C2[高内聚低耦合] D --> D1[数据库分离] D --> D2[团队自治] E --> E1[服务熔断] E --> E2[降级策略] F --> F1[语言无关] F --> F2[框架选择自由]

⚖️ 微服务vs单体应用对比#

维度	单体应用	微服务架构
开发复杂度	🟢 简单	🟡 复杂
部署方式	🟢 简单	🟡 复杂
技术栈	🟡 统一	🟢 多样化
扩展性	🔴 整体扩展	🟢 按需扩展
故障影响	🔴 全局影响	🟢 局部隔离
团队协作	🟡 需要协调	🟢 独立开发
数据一致性	🟢 ACID事务	🔴 最终一致性

🏗️ 微服务设计原则#

1. 单一职责原则 (Single Responsibility Principle)#

每个微服务应该专注于一个业务能力，遵循”做一件事并做好”的原则。

1
// ❌ 不好的设计 - 职责混乱
2
@Service
3
public class UserManagementService {
4
    public void createUser(User user) { /* 用户创建 */ }
5
    public void sendEmail(String email) { /* 邮件发送 */ }
6
    public void generateReport() { /* 报表生成 */ }
7
    public void processPayment(Payment payment) { /* 支付处理 */ }
8
}
9

10
// ✅ 好的设计 - 职责单一
11
@Service
12
public class UserService {
13
    public void createUser(User user) { /* 专注用户管理 */ }
14
    public void updateUser(User user) { /* */ }
15
    public User findUser(Long id) { /* */ }
16
}
17

18
@Service
19
public class NotificationService {
20
    public void sendEmail(String email) { /* 专注通知服务 */ }
21
    public void sendSms(String phone) { /* */ }
22
}

展开收起

2. 数据库分离原则#

1
# 每个服务拥有独立的数据存储
2
services:
3
  user-service:
4
    database: user_db
5
    technology: PostgreSQL
6

7
  order-service:
8
    database: order_db
9
    technology: MySQL
10

11
  product-service:
12
    database: product_db
13
    technology: MongoDB
14

15
  analytics-service:
16
    database: analytics_db
17
    technology: Elasticsearch

展开收起

3. 无状态设计#

1
// ✅ 无状态设计示例
2
@RestController
3
public class OrderController {
4

5
    @Autowired
6
    private OrderService orderService;
7

8
    @PostMapping("/orders")
9
    public ResponseEntity<Order> createOrder(@RequestBody CreateOrderRequest request,
10
                                           @RequestHeader("Authorization") String token) {
11
        // 从token解析用户信息，不依赖session状态
12
        User user = jwtTokenUtil.parseUser(token);
13
        Order order = orderService.createOrder(request, user);
14
        return ResponseEntity.ok(order);
15
    }
16
}

展开收起

🛠️ 技术栈选型指南#

Spring Cloud生态系统#

graph TB A[Spring Cloud Gateway] --> B[服务网关] C[Eureka/Consul] --> D[服务注册发现] E[Hystrix/Resilience4j] --> F[熔断降级] G[Spring Cloud Config] --> H[配置管理] I[Sleuth + Zipkin] --> J[链路追踪] K[Spring Security] --> L[安全认证] subgraph "完整技术栈" B D F H J L end

容器化部署#

1
# Dockerfile 最佳实践
2
FROM openjdk:11-jre-slim
3

4
# 创建非root用户
5
RUN groupadd -r spring && useradd -r -g spring spring
6

7
# 设置工作目录
8
WORKDIR /app
9

10
# 复制jar包
11
COPY target/user-service-*.jar app.jar
12

13
# 健康检查
14
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
15
  CMD curl -f http://localhost:8080/actuator/health || exit 1
16

17
# 切换到非root用户
18
USER spring:spring
19

20
# 启动应用
21
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

展开收起

🏪 实战案例：电商系统微服务化#

系统架构图#

graph TB subgraph "前端层" A[Web前端] B[移动端APP] C[管理后台] end subgraph "API网关层" D[Spring Cloud Gateway] end subgraph "微服务层" E[用户服务] F[商品服务] G[订单服务] H[支付服务] I[库存服务] J[通知服务] K[推荐服务] end subgraph "基础设施层" L[(用户数据库)] M[(商品数据库)] N[(订单数据库)] O[Redis缓存] P[消息队列] Q[文件存储] end A --> D B --> D C --> D D --> E D --> F D --> G D --> H D --> I D --> J D --> K E --> L F --> M G --> N E --> O F --> O G --> P H --> P I --> P J --> P K --> Q

服务拆分策略#

用户服务 (User Service)#

1
@RestController
2
@RequestMapping("/api/users")
3
public class UserController {
4

5
    @Autowired
6
    private UserService userService;
7

8
    @PostMapping("/register")
9
    public ResponseEntity<UserRegistrationResponse> register(
10
            @Valid @RequestBody UserRegistrationRequest request) {
11

12
        UserRegistrationResponse response = userService.registerUser(request);
13
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
14
    }
15

16
    @GetMapping("/{userId}")
17
    public ResponseEntity<UserDetailResponse> getUserDetail(@PathVariable Long userId) {
18
        UserDetailResponse response = userService.getUserDetail(userId);
19
        return ResponseEntity.ok(response);
20
    }
21

22
    @PutMapping("/{userId}/profile")
23
    public ResponseEntity<Void> updateProfile(@PathVariable Long userId,
24
                                            @Valid @RequestBody UpdateProfileRequest request) {
25
        userService.updateProfile(userId, request);
26
        return ResponseEntity.ok().build();
27
    }
28
}
29

30
@Service
31
@Transactional
32
public class UserService {
33

34
    @Autowired
35
    private UserRepository userRepository;
36

37
    @Autowired
38
    private PasswordEncoder passwordEncoder;
39

40
    @Autowired
41
    private ApplicationEventPublisher eventPublisher;
42

43
    public UserRegistrationResponse registerUser(UserRegistrationRequest request) {
44
        // 验证用户名是否已存在
45
        if (userRepository.existsByUsername(request.getUsername())) {
46
            throw new UserAlreadyExistsException("用户名已存在");
47
        }
48

49
        // 创建新用户
50
        User user = User.builder()
51
                .username(request.getUsername())
52
                .email(request.getEmail())
53
                .passwordHash(passwordEncoder.encode(request.getPassword()))
54
                .status(UserStatus.ACTIVE)
55
                .createdAt(LocalDateTime.now())
56
                .build();
57

58
        User savedUser = userRepository.save(user);
59

60
        // 发布用户注册事件
61
        eventPublisher.publishEvent(new UserRegisteredEvent(savedUser.getId(), savedUser.getEmail()));
62

63
        return UserRegistrationResponse.from(savedUser);
64
    }
65
}

展开收起

订单服务 (Order Service)#

1
@RestController
2
@RequestMapping("/api/orders")
3
public class OrderController {
4

5
    @Autowired
6
    private OrderService orderService;
7

8
    @PostMapping
9
    public ResponseEntity<CreateOrderResponse> createOrder(
10
            @Valid @RequestBody CreateOrderRequest request,
11
            @RequestHeader("X-User-Id") Long userId) {
12

13
        CreateOrderResponse response = orderService.createOrder(request, userId);
14
        return ResponseEntity.status(HttpStatus.CREATED).body(response);
15
    }
16

17
    @GetMapping("/{orderId}")
18
    public ResponseEntity<OrderDetailResponse> getOrderDetail(@PathVariable String orderId) {
19
        OrderDetailResponse response = orderService.getOrderDetail(orderId);
20
        return ResponseEntity.ok(response);
21
    }
22
}
23

24
@Service
25
@Transactional
26
public class OrderService {
27

28
    @Autowired
29
    private OrderRepository orderRepository;
30

31
    @Autowired
32
    private InventoryServiceClient inventoryServiceClient;
33

34
    @Autowired
35
    private PaymentServiceClient paymentServiceClient;
36

37
    @Autowired
38
    private RabbitTemplate rabbitTemplate;
39

40
    public CreateOrderResponse createOrder(CreateOrderRequest request, Long userId) {
41
        // 1. 验证库存
42
        List<InventoryCheckResult> inventoryResults =
43
            inventoryServiceClient.checkInventory(request.getItems());
44

45
        if (!inventoryResults.stream().allMatch(InventoryCheckResult::isAvailable)) {
46
            throw new InsufficientInventoryException("库存不足");
47
        }
48

49
        // 2. 创建订单
50
        Order order = Order.builder()
51
                .orderId(generateOrderId())
52
                .userId(userId)
53
                .items(request.getItems())
54
                .totalAmount(calculateTotalAmount(request.getItems()))
55
                .status(OrderStatus.PENDING_PAYMENT)
56
                .createdAt(LocalDateTime.now())
57
                .build();
58

59
        Order savedOrder = orderRepository.save(order);
60

61
        // 3. 预留库存
62
        inventoryServiceClient.reserveInventory(savedOrder.getOrderId(), request.getItems());
63

64
        // 4. 发送订单创建事件
65
        OrderCreatedEvent event = new OrderCreatedEvent(savedOrder.getOrderId(), userId, savedOrder.getTotalAmount());
66
        rabbitTemplate.convertAndSend("order.exchange", "order.created", event);
67

68
        return CreateOrderResponse.from(savedOrder);
69
    }
70
}

展开收起

服务间通信#

1. 同步通信 - Feign Client#

1
@FeignClient(name = "inventory-service", fallback = InventoryServiceFallback.class)
2
public interface InventoryServiceClient {
3

4
    @PostMapping("/api/inventory/check")
5
    List<InventoryCheckResult> checkInventory(@RequestBody List<OrderItem> items);
6

7
    @PostMapping("/api/inventory/reserve")
8
    void reserveInventory(@RequestParam String orderId, @RequestBody List<OrderItem> items);
9

10
    @PostMapping("/api/inventory/release")
11
    void releaseInventory(@RequestParam String orderId);
12
}
13

14
@Component
15
public class InventoryServiceFallback implements InventoryServiceClient {
16

17
    @Override
18
    public List<InventoryCheckResult> checkInventory(List<OrderItem> items) {
19
        // 降级策略：假设库存充足
20
        return items.stream()
21
                .map(item -> InventoryCheckResult.builder()
22
                        .productId(item.getProductId())
23
                        .available(true)
24
                        .availableQuantity(item.getQuantity())
25
                        .build())
26
                .collect(Collectors.toList());
27
    }
28

29
    @Override
30
    public void reserveInventory(String orderId, List<OrderItem> items) {
31
        log.warn("库存服务不可用，订单 {} 的库存预留操作已降级", orderId);
32
    }
33

34
    @Override
35
    public void releaseInventory(String orderId) {
36
        log.warn("库存服务不可用，订单 {} 的库存释放操作已降级", orderId);
37
    }
38
}

展开收起

2. 异步通信 - 消息队列#

1
@Component
2
public class OrderEventListener {
3

4
    @Autowired
5
    private InventoryService inventoryService;
6

7
    @Autowired
8
    private NotificationService notificationService;
9

10
    @RabbitListener(queues = "order.payment.success.queue")
11
    public void handlePaymentSuccess(PaymentSuccessEvent event) {
12
        try {
13
            // 确认库存扣减
14
            inventoryService.confirmInventoryDeduction(event.getOrderId());
15

16
            // 发送订单成功通知
17
            notificationService.sendOrderSuccessNotification(event.getUserId(), event.getOrderId());
18

19
        } catch (Exception e) {
20
            log.error("处理支付成功事件失败: orderId={}, error={}", event.getOrderId(), e.getMessage());
21
            // 重试机制或死信队列处理
22
            throw new RuntimeException(e);
23
        }
24
    }
25

26
    @RabbitListener(queues = "order.payment.failed.queue")
27
    public void handlePaymentFailed(PaymentFailedEvent event) {
28
        try {
29
            // 释放预留库存
30
            inventoryService.releaseReservedInventory(event.getOrderId());
31

32
            // 更新订单状态
33
            orderService.updateOrderStatus(event.getOrderId(), OrderStatus.PAYMENT_FAILED);
34

35
        } catch (Exception e) {
36
            log.error("处理支付失败事件失败: orderId={}, error={}", event.getOrderId(), e.getMessage());
37
        }
38
    }
39
}

展开收起

⚠️ 常见陷阱与解决方案#

1. 分布式事务问题#

问题描述：跨服务的数据一致性保证

解决方案：Saga模式

1
@Component
2
public class OrderSagaOrchestrator {
3

4
    public void processOrder(CreateOrderRequest request) {
5
        SagaTransaction saga = SagaTransaction.builder()
6
                .addStep(new CreateOrderStep())
7
                .addStep(new ReserveInventoryStep())
8
                .addStep(new ProcessPaymentStep())
9
                .addStep(new SendNotificationStep())
10
                .build();
11

12
        saga.execute(request);
13
    }
14
}
15

16
public class CreateOrderStep implements SagaStep {
17

18
    @Override
19
    public void execute(Object data) {
20
        // 创建订单逻辑
21
    }
22

23
    @Override
24
    public void compensate(Object data) {
25
        // 取消订单逻辑
26
    }
27
}

展开收起

2. 服务雪崩问题#

问题描述：单个服务故障导致连锁反应

解决方案：熔断器 + 降级策略

1
@Service
2
public class ProductService {
3

4
    @Autowired
5
    private ProductServiceClient productServiceClient;
6

7
    @CircuitBreaker(name = "product-service", fallbackMethod = "getProductDetailFallback")
8
    @TimeLimiter(name = "product-service")
9
    @Retry(name = "product-service")
10
    public CompletableFuture<ProductDetail> getProductDetail(Long productId) {
11
        return CompletableFuture.supplyAsync(() ->
12
            productServiceClient.getProductDetail(productId));
13
    }
14

15
    public CompletableFuture<ProductDetail> getProductDetailFallback(Long productId, Exception ex) {
16
        // 降级策略：返回基础商品信息
17
        return CompletableFuture.completedFuture(
18
            ProductDetail.builder()
19
                .id(productId)
20
                .name("商品信息暂时无法获取")
21
                .available(false)
22
                .build()
23
        );
24
    }
25
}

展开收起

3. 配置管理复杂性#

解决方案：统一配置中心

application-dev.yml展开收起

1
spring:
2
  cloud:
3
    config:
4
      uri: http://config-server:8888
5
      profile: dev
6
      label: master
7
  application:
8
    name: order-service
9

10
# bootstrap.yml
11
spring:
12
  cloud:
13
    config:
14
      uri: ${CONFIG_SERVER_URL:http://localhost:8888}
15
      fail-fast: true
16
      retry:
17
        max-attempts: 3
18
        max-interval: 2000

展开收起

🚀 总结与展望#

微服务架构是一把双刃剑，它带来了：

收益：

🎯 技术栈多样化和团队独立性
📈 按需扩展和故障隔离
🔄 快速迭代和持续部署

挑战：

🌐 分布式系统复杂性
📊 运维和监控难度增加
🔄 数据一致性保证

最佳实践总结#

渐进式迁移：从边缘服务开始，逐步分解单体应用
监控为先：建立完善的监控、日志和追踪体系
自动化测试：构建完整的测试金字塔
文档驱动：维护API文档和架构决策记录
团队协作：建立跨团队沟通机制

💡 记住：微服务不是银弹，要根据团队规模、业务复杂度和技术能力来选择合适的架构策略。

📖 相关阅读#

如果这篇文章对你有帮助，欢迎点赞、分享和评论！ 🌟

CloudFlare-ImgBed 网页上传 JPG/PNG 自动转 WebP 并保存到 Telegram 教程

Sat, 18 Jul 2026 00:00:00 GMT

本文说明如何在 CloudFlare-ImgBed 中实现以下流程：用户通过网页选择 JPG、JPEG 或 PNG 图片后，浏览器先把图片转换成 WebP，再将 WebP 上传到 Cloudflare Worker，最后由 Telegram Bot 以原文件形式保存到 Telegram Channel。

本教程对应本仓库当前实现。它只处理网页上传入口，不会自动转换 PicGo、WebDAV、API 脚本或其他直接调用 /upload 的客户端。

1. 最终效果#

只转换 image/jpeg 和 image/png。
WebP 编码质量为 0.85，即 85%。
不改变图片宽高。
PNG 透明通道保留。
GIF、SVG、已有 WebP 和非图片文件保持原样。
WebP 转换失败时回退上传原文件，不中断上传。
转换后的 WebP 不再经过旧客户端压缩库二次编码。
WebP 上传 Telegram 时使用 sendDocument，保留 .webp 文件名和 image/webp MIME。
HTML 入口由 Worker-first 处理并返回 no-store，避免自定义域长期使用旧的前端清单。

正常上传请求应类似：

1
POST /upload?serverCompress=false&uploadChannel=telegram&...

上传成功后，图床文件名和返回链接应以 .webp 结尾。

2. 整体架构#

flowchart LR A["浏览器选择 JPG/PNG"] --> B["Canvas 转换为 WebP，质量 85%"] B --> C["跳过旧客户端二次压缩"] C --> D["POST /upload，serverCompress=false"] D --> E["Cloudflare Worker"] E --> F["Telegram Bot sendDocument"] F --> G["Telegram Channel 保存 .webp"]

转换发生在浏览器中，因此不会消耗 Cloudflare Worker 的图片编码 CPU，也不需要在 Worker 中引入 WebAssembly 图片编码器。

3. 源码级改造实录#

这一节给出具体的源码修改。整体思路不是再搭建一个图片处理服务器，而是直接改造原项目已有的四段链路：

1
网页上传前处理
2
→ /upload Worker 接口
3
→ Telegram Bot API
4
→ Worker 静态资源发布

说明：当前后端仓库没有提交完整 Vue 前端源码，只有 frontend-dist 和 source map。下面先用 source map 中还原出的 UploadForm.vue 代码展示“应该修改什么”，然后给出本仓库实际使用的部署前补丁代码。

3.1 前端：只转换 JPG/PNG#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 beforeUpload(file) 方法。
实际修改文件：scripts/patch-webp-upload.mjs，部署时修改对应的 frontend-dist/js/923.*.js bundle。

原上传逻辑只排除了 WebP、GIF 和 SVG，其他图片格式都会尝试转换：

1
const canConvertToWebp = this.convertToWebp
2
  && file.type.includes('image')
3
  && !file.type.includes('webp')
4
  && !file.type.includes('gif')
5
  && !file.type.includes('svg');
6
const canConvertToWebp = this.convertToWebp
7
  && ['image/jpeg', 'image/png'].includes(file.type);

这样 BMP、GIF、SVG、ICO 等格式不会进入该转换分支。

3.2 前端：把 WebP 质量从 92% 调整为 85%#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 convertImageToWebp(file) 方法。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，替换上传 bundle 中 Canvas toBlob 的 WebP 质量参数。

原来的 Canvas 编码参数为 0.92：

1
canvas.toBlob(blob => {
2
  // 将 Blob 包装为 File
3
}, 'image/webp', 0.92);
4
}, 'image/webp', 0.85);

转换成功后保留原来的宽高，只改变编码格式和文件名：

1
const originalName = file.name;
2
const lastDotIndex = originalName.lastIndexOf('.');
3
const newName = lastDotIndex > 0
4
  ? `${originalName.substring(0, lastDotIndex)}.webp`
5
  : `${originalName}.webp`;
6

7
const webpFile = new File([blob], newName, {
8
  type: 'image/webp',
9
});
10
webpFile.uid = file.uid;

3.3 前端：强制初始化 WebP 开关#

源码语义位置：前端 src/views/UploadHome.vue 的 mounted() 初始化逻辑。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，替换上传页面 bundle 中 this.convertToWebp 的初始化表达式。

原项目会优先读取 Vuex 持久化设置。旧浏览器如果曾保存过 convertToWebp=false，即使系统默认值改成 true，也仍然不会转换：

1
this.convertToWebp = this.compressConfig.convertToWebp
2
  ?? this.parseBoolean(this.userConfig?.defaultConvertToWebp, false);
3
this.convertToWebp = true;

这样页面每次初始化时都会启用 JPG/PNG 转 WebP。

3.4 前端：阻止 WebP 二次压缩#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 beforeUpload(file) 方法，在 needCustomCompress 判断处。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，修改 bundle 中 customerCompress 的条件表达式。

原项目在 WebP 转换之后，还会执行 imageConversion.compressAccurately：

1
const needCustomCompress = processedFile.type.includes('image')
2
  && this.customerCompress
3
  && processedFile.size / 1024 / 1024 > this.compressBar;

但当前 image-conversion 版本只正确支持 PNG、JPEG 和 GIF 输出。把 WebP 再交给它，可能重新编码成 JPEG/PNG，或者造成文件名与 MIME 不一致。

修改为：本次进入 WebP 转换分支时，不再执行旧客户端压缩。

1
const needCustomCompress = processedFile.type.includes('image')
2
const needCustomCompress = !canConvertToWebp
3
  && processedFile.type.includes('image')
4
  && this.customerCompress
5
  && processedFile.size / 1024 / 1024 > this.compressBar;

85% WebP 编码本身已经完成压缩，不需要再编码一次。

3.5 前端：WebP 关闭 Telegram 服务端压缩#

源码语义位置：前端 src/components/upload/UploadForm.vue 的 beforeUpload(file) 方法，在 pushFileToQueue() 写入 fileList 时。
当前仓库实际修改文件：scripts/patch-webp-upload.mjs，修改 bundle 中 serverCompress 字段。

上传队列原本直接保存计算出的 serverCompress：

1
this.fileList.push({
2
  uid: file.uid,
3
  name: file.name,
4
  serverCompress,
5
  serverCompress: canConvertToWebp ? false : serverCompress,
6
  retryCount: 0,
7
});

最终 WebP 请求会变成：

1
POST /upload?serverCompress=false&uploadChannel=telegram&...

如果 Network 中仍看到 serverCompress=true，说明当前页面没有执行到新 WebP 分支，通常是自定义域仍访问旧 Worker。

3.6 实际落地：部署前修改编译 bundle#

新增文件：scripts/patch-webp-upload.mjs。
读取目录：frontend-dist/js。
运行时修改：当前版本的上传 chunk frontend-dist/js/923.*.js 及对应 .js.gz；上游更新后 chunk 哈希可能变化，因此脚本通过内容锚点查找，不依赖固定文件名。

由于当前仓库只有编译后的前端，本方案新增一个 Node.js 补丁脚本。脚本在 frontend-dist/js 中寻找上传 bundle，并修改以下锚点：

1
const ORIGINAL_CONDITION = /this\.convertToWebp&&([A-Za-z_$][\w$]*)\.type\.includes\("image"\)&&!\1\.type\.includes\("webp"\)&&!\1\.type\.includes\("gif"\)&&!\1\.type\.includes\("svg"\)/g;
2

3
const PATCHED_CONDITION = /this\.convertToWebp&&\["image\/jpeg","image\/png"\]\.includes\(([A-Za-z_$][\w$]*)\.type\)/g;
4

5
const ORIGINAL_QUALITY = /"image\/webp",\.92/g;
6
const PATCHED_QUALITY = /"image\/webp",\.85/g;
7

8
const ORIGINAL_CLIENT_COMPRESSION = /const i=a\.type\.includes\("image"\)&&this\.customerCompress&&a\.size\/1024\/1024>this\.compressBar/g;
9
const PATCHED_CLIENT_COMPRESSION = /const i=!s&&a\.type\.includes\("image"\)&&this\.customerCompress&&a\.size\/1024\/1024>this\.compressBar/g;
10

11
const ORIGINAL_SERVER_COMPRESSION = /serverCompress:o,retryCount:0/g;
12
const PATCHED_SERVER_COMPRESSION = /serverCompress:o&&!s,retryCount:0/g;

核心替换代码如下：

1
if (originalConditionCount === 1) {
2
  patched = patched.replace(
3
    ORIGINAL_CONDITION,
4
    (original, fileVariable) => {
5
      const replacement =
6
        `this.convertToWebp&&["image/jpeg","image/png"].includes(${fileVariable}.type)`;
7

8
      // 保持长度，尽量避免破坏原 source map 的后续列位置。
9
      return replacement.padEnd(original.length, ' ');
10
    },
11
  );
12
}
13

14
if (originalQualityCount === 1) {
15
  patched = patched.replace(
16
    ORIGINAL_QUALITY,
17
    '"image/webp",.85',
18
  );
19
}
20

21
if (originalClientCompressionCount === 1) {
22
  patched = patched.replace(
23
    ORIGINAL_CLIENT_COMPRESSION,
24
    'const i=!s&&a.type.includes("image")&&this.customerCompress&&a.size/1024/1024>this.compressBar',
25
  );
26
}
27

28
if (originalServerCompressionCount === 1) {
29
  patched = patched.replace(
30
    ORIGINAL_SERVER_COMPRESSION,
31
    'serverCompress:o&&!s,retryCount:0',
32
  );
33
}

展开收起

补丁写入 JavaScript 后，同步重新生成 .gz：

1
writeFileSync(candidate.jsPath, candidate.content);
2
writeFileSync(
3
  `${candidate.jsPath}.gz`,
4
  gzipSync(Buffer.from(candidate.content)),
5
);

脚本还会验证每个原始或已修改锚点只出现一次。如果匹配不到，直接抛出错误：

1
throw new Error(
2
  'No compatible WebP upload bundle was found; the upstream frontend may have changed.',
3
);

这可以避免上游更新前端后，GitHub Actions 看似部署成功，但 WebP 功能已经静默失效。

3.7 增加 npm 命令#

修改文件：package.json。
修改位置：顶层 scripts 对象。

在 package.json 的 scripts 中增加：

1
{
2
  "scripts": {
3
    "patch:webp": "node scripts/patch-webp-upload.mjs frontend-dist"
4
  }
5
}

本地可以执行：

Terminal window

1
npm run patch:webp

3.8 修改 GitHub Actions 顺序#

修改文件：.github/workflows/deploy-worker.yml。
新增位置：jobs.deploy.steps 中，位于 Install dependencies 和 Generate worker routes 之间。

在 Worker 部署工作流中，把 WebP 补丁放在 Wrangler 收集静态资源之前：

1
- name: Install dependencies
2
  if: steps.check.outputs.skip != 'true'
3
  run: npm ci --omit=dev --omit=optional
4

5
- name: Apply WebP upload customization
6
  if: steps.check.outputs.skip != 'true'
7
  run: npm run patch:webp
8

9
- name: Generate worker routes
10
  if: steps.check.outputs.skip != 'true'
11
  run: node deploy/worker/generate-routes.js
12

13
- name: Generate wrangler config
14
  if: steps.check.outputs.skip != 'true'
15
  run: node deploy/worker/generate-toml.js
16

17
- name: Deploy to Cloudflare Workers
18
  if: steps.check.outputs.skip != 'true'
19
  uses: cloudflare/wrangler-action@v3
20
  with:
21
    apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
22
    accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
23
    wranglerVersion: '4'
24
    command: deploy --config deploy/worker/wrangler.toml

展开收起

最终顺序是：

1
安装依赖
2
→ 修改前端 bundle
3
→ 生成 Worker 路由
4
→ 生成 Wrangler 配置
5
→ 部署代码与静态资源

3.9 后端：删除 WebP 改名为 JPEG 的逻辑#

删除位置：functions/upload/index.js。
所属函数：uploadFileToTelegram(context, fullId, metadata, fileExt, fileName, fileType, returnLink)。

原 Telegram 上传代码为了规避 animation 行为，会把 WebP 文件名改成 .jpeg：

1
if (fileExt === 'gif') {
2
  const newFileName = fileName.replace(/\.gif$/, '.jpeg');
3
  const newFile = new File([formdata.get('file')], newFileName, {
4
    type: fileType,
5
  });
6
  formdata.set('file', newFile);
7
} else if (fileExt === 'webp') {
8
  const newFileName = fileName.replace(/\.webp$/, '.jpeg');
9
  const newFile = new File([formdata.get('file')], newFileName, {
10
    type: fileType,
11
  });
12
  formdata.set('file', newFile);
13
}

修改后只保留 GIF 兼容处理，WebP 文件名保持 photo.webp。

实际代码把文件名规则抽成函数：

1
export function getTelegramStoredFileName(fileName, fileExt) {
2
  if ((fileExt || '').toLowerCase() === 'gif') {
3
    return fileName.replace(/\.gif$/i, '.jpeg');
4
  }
5
  return fileName;
6
}

上传前应用该规则：

1
const telegramFileName = getTelegramStoredFileName(
2
  fileName,
3
  fileExt,
4
);
5

6
if (telegramFileName !== fileName) {
7
  const renamedFile = new File(
8
    [formdata.get('file')],
9
    telegramFileName,
10
    { type: fileType },
11
  );
12
  formdata.set('file', renamedFile);
13
}

对于 WebP，函数直接返回原文件名，因此不会发生重命名。

3.10 后端：WebP 改用 sendDocument#

删除位置：functions/upload/index.js 的 uploadFileToTelegram()，原 fileTypeMap 和 GIF/WebP 特殊接口判断区域。
新增文件：functions/upload/telegramUploadPolicy.js，新增 selectTelegramSendFunction()。
调用位置：functions/upload/index.js 的 uploadFileToTelegram()，在调用 telegramAPI.sendFile() 之前。

原策略把 WebP 发送为 animation：

1
if (
2
  fileType === 'image/gif'
3
  || fileType === 'image/webp'
4
  || fileExt === 'gif'
5
  || fileExt === 'webp'
6
) {
7
  sendFunction = {
8
    url: 'sendAnimation',
9
    type: 'animation',
10
  };
11
}

改造后的策略如下：

1
const DOCUMENT = {
2
  url: 'sendDocument',
3
  type: 'document',
4
};
5

6
export function selectTelegramSendFunction(
7
  fileType = '',
8
  fileExt = '',
9
  serverCompress = true,
10
) {
11
  const normalizedType = fileType.toLowerCase();
12
  const normalizedExt = fileExt.toLowerCase();
13

14
  // WebP 永远作为原始 document 保存。
15
  if (
16
    !serverCompress
17
    || normalizedType === 'image/webp'
18
    || normalizedExt === 'webp'
19
  ) {
20
    return { ...DOCUMENT };
21
  }
22

23
  if (
24
    normalizedType === 'image/gif'
25
    || normalizedExt === 'gif'
26
  ) {
27
    return {
28
      url: 'sendAnimation',
29
      type: 'animation',
30
    };
31
  }
32

33
  if (normalizedType.startsWith('image/')) {
34
    return {
35
      url: 'sendPhoto',
36
      type: 'photo',
37
    };
38
  }
39

40
  return { ...DOCUMENT };
41
}

展开收起

Worker 上传区域调用：

1
const serverCompress =
2
  url.searchParams.get('serverCompress') !== 'false';
3

4
const sendFunction = selectTelegramSendFunction(
5
  fileType,
6
  fileExt,
7
  serverCompress,
8
);
9

10
const response = await telegramAPI.sendFile(
11
  formdata.get('file'),
12
  tgChatId,
13
  sendFunction.url,
14
  sendFunction.type,
15
);

展开收起

3.11 Telegram API：关闭内容类型自动识别#

修改文件：functions/utils/storage/telegramAPI.js。
所属方法：TelegramAPI.sendFile(file, chatId, functionName, functionType, caption, fileName)。
新增位置：构造完 FormData、调用 fetch() 之前。

构造 Telegram multipart 请求时，为 sendDocument 增加：

1
if (functionName === 'sendDocument') {
2
  formData.append(
3
    'disable_content_type_detection',
4
    'true',
5
  );
6
}

完整关键部分：

1
const formData = new FormData();
2
formData.append('chat_id', chatId);
3
formData.append(functionType, file);
4

5
if (caption) {
6
  formData.append('caption', caption);
7
}
8

9
if (functionName === 'sendDocument') {
10
  formData.append(
11
    'disable_content_type_detection',
12
    'true',
13
  );
14
}
15

16
const response = await fetch(
17
  `${this.baseURL}/${functionName}`,
18
  {
19
    method: 'POST',
20
    headers: this.defaultHeaders,
21
    body: formData,
22
  },
23
);

展开收起

这保证 Telegram 收到：

1
字段名：document
2
文件名：photo.webp
3
MIME：image/webp
4
disable_content_type_detection：true

3.12 Telegram API：返回真实错误#

修改文件一：functions/utils/storage/telegramAPI.js 的 TelegramAPI.sendFile()，删除只使用 response.statusText 的错误处理，改为解析 JSON description。
修改文件二：functions/upload/index.js 的 uploadFileToTelegram() catch 分支，删除固定通用错误，改为调用格式化函数。
新增位置：functions/upload/telegramUploadPolicy.js 中增加 formatTelegramUploadError()。

原代码只使用 HTTP statusText：

1
if (!response.ok) {
2
  throw new Error(
3
    `Telegram API error: ${response.statusText}`,
4
  );
5
}

修改后先解析 JSON，再读取 Bot API 的 description：

1
let responseData = null;
2

3
try {
4
  responseData = await response.json();
5
} catch (error) {
6
  if (response.ok) {
7
    throw new Error(
8
      `Telegram API returned invalid JSON: ${error.message}`,
9
    );
10
  }
11
}
12

13
if (!response.ok || responseData?.ok === false) {
14
  const description = responseData?.description
15
    || response.statusText
16
    || `HTTP ${response.status}`;
17

18
  throw new Error(
19
    `Telegram API error: ${description}`,
20
  );
21
}

展开收起

上传入口不再把异常替换成固定字符串，而是保留真实错误：

1
} catch (error) {
2
  res = createResponse(
3
    'upload error, check your environment params about telegram channel!',
4
    { status: 400 },
5
  );
6
  res = createResponse(
7
    `upload error: ${error.message}`,
8
    { status: 502 },
9
  );
10
}

3.13 Worker 静态资源：启用 Worker-first#

修改文件一：deploy/worker/wrangler.toml 的 [assets] 段。
修改文件二：deploy/worker/generate-toml.js 中生成 [assets] 的模板字符串。
必须同时修改两处，因为 GitHub Actions 部署时会重新生成 wrangler.toml。

在 Wrangler 的 [assets] 中增加：

1
[assets]
2
directory = "../../frontend-dist"
3
binding = "ASSETS"
4
not_found_handling = "single-page-application"
5
run_worker_first = true

因为 GitHub Actions 会动态生成 wrangler.toml，不仅要改本地 TOML，还要在生成脚本模板中加入同一行：

1
let toml = `
2
[assets]
3
directory = "../../frontend-dist"
4
binding = "ASSETS"
5
not_found_handling = "single-page-application"
6
run_worker_first = true
7
`;

3.14 Worker 静态资源：HTML 不缓存#

修改源文件：deploy/worker/generate-routes.js 的 Worker 输出模板。
新增函数：fetchWorkerAsset(request, env)。
替换位置：生成模板中 if (!matched) 的 env.ASSETS.fetch(request) 回退。
生成文件：运行脚本后同步更新 deploy/worker/index.js；该文件是生成结果，不应只手工修改它。

在 Worker 的静态资源回退处新增：

1
async function fetchWorkerAsset(request, env) {
2
  const response = await env.ASSETS.fetch(request);
3
  const contentType =
4
    response.headers.get('Content-Type') || '';
5

6
  // JS/CSS/图片等带哈希资源继续正常缓存。
7
  if (!contentType.toLowerCase().includes('text/html')) {
8
    return response;
9
  }
10

11
  const headers = new Headers(response.headers);
12
  headers.set(
13
    'Cache-Control',
14
    'no-store, no-cache, must-revalidate',
15
  );
16
  headers.set('CDN-Cache-Control', 'no-store');
17
  headers.set(
18
    'Cloudflare-CDN-Cache-Control',
19
    'no-store',
20
  );
21
  headers.set(
22
    'X-ImgBed-Asset-Policy',
23
    'worker-first-no-store',
24
  );
25
  headers.delete('ETag');
26

27
  return new Response(response.body, {
28
    status: response.status,
29
    statusText: response.statusText,
30
    headers,
31
  });
32
}

展开收起

原来的资产回退：

1
if (!matched) {
2
  if (env.ASSETS) {
3
    return env.ASSETS.fetch(request);
4
    return fetchWorkerAsset(request, env);
5
  }
6
  return new Response('Not Found', {
7
    status: 404,
8
  });
9
}

这样 HTML 每次从当前部署的 ASSETS binding 获取，而带哈希的静态资源仍保留缓存性能。

3.15 Cloudflare 控制台：删除旧 Workers Route#

非仓库文件修改：Cloudflare Dashboard → 域名 → Workers 路由。
删除对象：仍指向旧 Worker 的 tu.example.com/* Route。
不要删除旧 Worker 服务本身，只删除它对当前图床域名的路由占用。

代码部署成功后，还必须检查 Cloudflare 的“Workers 路由”。如果存在：

1
tu.example.com/* → old-image-worker

即使新 Worker 已配置 Custom Domain，该旧 Route 仍可能接管请求。删除旧 Route，只保留：

1
tu.example.com → cloudflare-imgbed

这是本次实际排查中导致自定义域一直加载旧前端的根因。它不是代码 Bug，而是旧路由仍指向旧 Worker。

3.16 对应的回归测试#

新增或修改的测试文件：

test/webp-upload-patcher.test.js：前端 bundle 补丁、85% 质量、二次压缩和 serverCompress。
test/telegram-upload-policy.test.js：WebP 文件名和 Telegram 发送策略。
test/telegram-api.test.js：sendDocument 参数及真实错误描述。
test/worker-asset-cache.test.js：Worker-first 和 HTML no-store。

至少应覆盖以下断言：

1
assert.ok(
2
  patched.includes(
3
    '["image/jpeg","image/png"].includes(',
4
  ),
5
);
6
assert.ok(patched.includes('"image/webp",.85'));
7
assert.ok(
8
  patched.includes(
9
    'serverCompress:o&&!s,retryCount:0',
10
  ),
11
);

Telegram 策略测试：

1
assert.equal(
2
  getTelegramStoredFileName('photo.webp', 'webp'),
3
  'photo.webp',
4
);
5

6
assert.deepEqual(
7
  selectTelegramSendFunction(
8
    'image/webp',
9
    'webp',
10
    true,
11
  ),
12
  {
13
    url: 'sendDocument',
14
    type: 'document',
15
  },
16
);

展开收起

Worker 静态资源测试：

1
assert.match(
2
  wranglerConfig,
3
  /run_worker_first\s*=\s*true/,
4
);
5

6
assert.match(
7
  generatedWorker,
8
  /worker-first-no-store/,
9
);

完整测试命令：

Terminal window

1
npm test

3.17 增删改文件汇总#

文件或配置	操作	具体位置与作用
`scripts/patch-webp-upload.mjs`	新增	查找并修改 `frontend-dist/js` 上传 bundle，设置 JPG/PNG → WebP、质量 85%、跳过二次压缩、关闭 `serverCompress`，并重建 `.gz`
`package.json`	修改	在 `scripts` 中增加 `patch:webp` 命令
`.github/workflows/deploy-worker.yml`	修改	在 Wrangler 构建前增加 `Apply WebP upload customization` 步骤
`functions/upload/index.js`	删除、修改	在 `uploadFileToTelegram()` 中删除 WebP 改名 `.jpeg` 和 `sendAnimation` 处理；调用新策略并透传错误
`functions/upload/telegramUploadPolicy.js`	新增	集中处理 Telegram 文件名、`sendDocument` 策略和错误格式化
`functions/utils/storage/telegramAPI.js`	修改	在 `sendFile()` 中增加 `disable_content_type_detection`，解析 Telegram JSON 错误描述
`deploy/worker/wrangler.toml`	修改	在 `[assets]` 中增加 `run_worker_first = true`
`deploy/worker/generate-toml.js`	修改	让 GitHub Actions 生成的 Wrangler 配置也包含 Worker-first
`deploy/worker/generate-routes.js`	修改	在生成模板中增加 `fetchWorkerAsset()` 和 HTML no-store 响应头
`deploy/worker/index.js`	生成更新	由 `generate-routes.js` 重新生成，包含 Worker-first 的资产回退逻辑
`test/webp-upload-patcher.test.js`	修改	验证前端补丁和失败保护
`test/telegram-upload-policy.test.js`	新增	验证 WebP 文件名、document 策略和错误格式
`test/telegram-api.test.js`	新增	验证 Telegram multipart 和错误描述
`test/worker-asset-cache.test.js`	新增	验证 Worker-first 和 HTML no-store
Cloudflare Workers Route	删除控制台配置	删除 `tu.example.com/* → old-image-worker`，防止旧 Worker 抢先接管自定义域

4. 前端 WebP 转换策略#

npm run patch:webp 最终让上传逻辑遵循以下条件：

1
文件 MIME 是 image/jpeg 或 image/png
2
并且 WebP 转换已启用

转换参数：

1
输出 MIME：image/webp
2
质量：0.85
3
尺寸：保持原图尺寸

转换完成后会生成新的浏览器 File：

1
原文件：photo.png，image/png
2
新文件：photo.webp，image/webp

4.1 为什么必须跳过二次客户端压缩#

项目原有的 image-conversion 版本只正确支持 PNG、JPEG 和 GIF 输出，不支持 WebP 输出。如果先转换 WebP，再把 WebP 交给该库，可能发生：

再次解码和编码，导致上传前处理明显变慢；
输出变回 JPEG/PNG；
文件扩展名和真实二进制 MIME 不一致。

因此 WebP 转换成功后必须绕过旧客户端压缩逻辑。85% WebP 编码本身已经完成了有损压缩，不需要再压缩一次。

5. Telegram 保存策略#

5.1 使用 sendDocument#

Telegram Bot API 对图片提供 sendPhoto、sendAnimation 和 sendDocument 等接口。要保留 WebP 原始内容，必须使用：

1
sendDocument

不能使用 sendPhoto，否则 Telegram 可能重新压缩图片；也不应把静态 WebP 当作 animation。

5.2 保留文件名和 MIME#

上传到 Telegram 的 multipart 字段应保持：

1
filename="photo.webp"
2
Content-Type: image/webp

同时为 sendDocument 添加：

1
disable_content_type_detection=true

这可以避免 Telegram 根据文件内容自动改变 document 类型。

5.3 Telegram 错误透传#

Telegram API 失败时，后端会读取响应 JSON 中的 description。前端最终可以看到类似：

1
upload error: Telegram API error: Bad Request: ...

而不是没有诊断价值的通用错误：

1
upload error, check your environment params about telegram channel!

6. GitHub Actions 部署流程#

.github/workflows/deploy-worker.yml 的核心顺序是：

1
Checkout
2
→ npm ci --omit=dev --omit=optional
3
→ npm run patch:webp
4
→ node deploy/worker/generate-routes.js
5
→ node deploy/worker/generate-toml.js
6
→ wrangler deploy

其中 WebP 补丁必须发生在 Wrangler 收集 frontend-dist 静态资源之前。

6.1 必需的 GitHub Secrets#

进入：

1
GitHub 仓库
2
→ Settings
3
→ Secrets and variables
4
→ Actions

至少配置：

Secret	说明
`CLOUDFLARE_API_TOKEN`	具有 Worker 部署权限的 API Token
`CLOUDFLARE_ACCOUNT_ID`	Worker 所在 Cloudflare 账号 ID
`KV_NAMESPACE_ID` 或 `D1_DATABASE_ID`	图床数据库绑定，按实际部署方式选择

可选：

Secret	说明
`WORKER_NAME`	Worker 名称；为空时默认 `cloudflare-imgbed`
`R2_BUCKET_NAME`	使用 R2 时填写
`WORKER_VARS`	JSON 格式的业务环境变量

不要把 Bot Token、API Token 或其他密钥直接写进仓库文件。

6.2 手动部署#

GitHub 仓库的 Actions 页面选择：

1
Deploy to Cloudflare Workers
2
→ Run workflow
3
→ Branch: main

如需覆盖 Worker 名称，可在 worker_name 中填写实际服务名称。

7. Cloudflare 自定义域名配置#

GitHub Actions 只负责把代码部署到 Worker，不会根据 Account ID 自动推断域名应该绑定哪个服务。域名绑定需要在 Cloudflare 中单独完成一次。

例如：

1
Worker：cloudflare-imgbed
2
Worker URL：cloudflare-imgbed.<account-subdomain>.workers.dev
3
自定义域名：tu.example.com

进入：

1
Cloudflare Dashboard
2
→ Workers 和 Pages
3
→ cloudflare-imgbed
4
→ 域
5
→ 添加域名

添加：

1
tu.example.com

添加成功后，DNS 记录中应显示该子域名的类型为 Worker，目标为 cloudflare-imgbed。

7.1 删除旧 CNAME#

如果添加域名时报错：

1
Hostname already has externally managed DNS records

说明该子域名已经存在 A 或 CNAME。例如：

1
tu.example.com CNAME example.com

需要先删除这条旧记录，再通过 Worker 的“添加域名”功能创建 Custom Domain。删除子域名记录不会删除根域名网站。

7.2 必须检查旧 Workers Route#

Custom Domain 配置正确后，还要检查：

1
Cloudflare → 域名 → Workers 路由

旧部署可能存在：

1
tu.example.com/* → old-image-worker

该 Route 会抢先接管请求，使 Custom Domain 虽然显示绑定新 Worker，实际仍访问旧 Worker。推荐删除旧路由，只保留：

1
tu.example.com → cloudflare-imgbed Custom Domain

本项目排查时的实际根因就是一条旧路由仍指向旧图床 Worker。

8. Worker Static Assets 缓存处理#

Wrangler 资产配置启用了：

1
[assets]
2
directory = "../../frontend-dist"
3
binding = "ASSETS"
4
not_found_handling = "single-page-application"
5
run_worker_first = true

run_worker_first = true 确保 HTML 请求先进入当前部署的 Worker，再读取当前 ASSETS binding。

HTML 响应会带上：

1
Cache-Control: no-store, no-cache, must-revalidate
2
CDN-Cache-Control: no-store
3
Cloudflare-CDN-Cache-Control: no-store
4
X-ImgBed-Asset-Policy: worker-first-no-store

带哈希的 JS、CSS、字体和图片仍可缓存，以保持访问性能。

不建议长期为整个图床域名创建“绕过所有缓存”的 Cache Rule。确认旧 Worker Route 已删除且 Worker-first 生效后，可以删除临时缓存绕过规则。

9. 本地测试#

安装依赖：

Terminal window

1
npm ci

运行全部测试：

Terminal window

1
npm test

当前测试覆盖：

只转换 JPG/PNG；
WebP 质量为 85%；
跳过二次客户端压缩；
WebP 禁用 Telegram 服务端压缩；
补丁幂等性；
不兼容前端 bundle 时阻止部署；
Telegram WebP 文件名和 sendDocument 策略；
Telegram API 错误描述；
Worker-first 和 HTML no-store 策略。

单独验证部署前补丁：

Terminal window

1
npm run patch:webp

注意：该命令会直接修改本地 frontend-dist 构建产物。GitHub Actions 中执行时，只修改临时 checkout，不会把生成结果自动提交回仓库。

10. 上线验证#

10.1 先验证 workers.dev#

先访问 Worker 原始地址：

1
https://cloudflare-imgbed.<account-subdomain>.workers.dev

开发者工具 Network 中，HTML Document 响应应包含：

1
X-ImgBed-Asset-Policy: worker-first-no-store

10.2 再验证自定义域名#

访问：

1
https://tu.example.com

它必须加载与 workers.dev 相同的前端资源。若两个域名加载的 app.*.js 哈希不同，通常不是浏览器缓存问题，而是：

旧 Workers Route 仍指向旧服务；
自定义域名绑定到了错误 Worker；
DNS 仍是旧 CNAME；
请求被其他重定向、源站或配置规则接管。

10.3 验证上传请求#

上传新的 JPG/PNG，在 Network 中检查 /upload：

1
serverCompress=false
2
uploadChannel=telegram

如果仍是：

1
serverCompress=true

说明当前页面没有执行 WebP 转换。优先检查浏览器加载的上传 bundle 是否为新版本，以及自定义域是否仍指向旧 Worker。

10.4 验证最终文件#

确认以下项目：

返回 URL 以 .webp 结尾；
管理面板显示 image/webp；
Telegram 消息类型为 Document；
Telegram 文件名以 .webp 结尾；
下载后的文件可被 WebP 解码器正常识别。

11. 常见问题#

Q1：为什么上传解析变慢，但文件还是 PNG？#

常见原因是 WebP 转换开关被浏览器持久化配置覆盖，或者转换后又进入旧客户端压缩库。本方案强制初始化 WebP，并阻止转换后的文件二次压缩。

Q2：为什么请求一直是 `serverCompress=true`？#

说明该文件没有进入成功的 WebP 分支，或者页面仍是旧前端。检查：

原文件 MIME 是否为 image/jpeg 或 image/png；
自定义域和 workers.dev 是否加载同一版前端；
是否存在旧 Workers Route；
上传 bundle 中是否包含 85% WebP 补丁。

Q3：为什么 `cf-cache-status` 仍显示 HIT？#

带哈希的 JS、CSS 和图片命中 Workers Static Assets 缓存是正常现象。判断 HTML 是否经过新 Worker，应检查 Document 响应中的：

1
X-ImgBed-Asset-Policy: worker-first-no-store

不要只查看旧 app.<hash>.js 的响应头。

Q4：为什么 Telegram 上传失败后所有备用渠道也报错？#

项目开启自动重试后，会依次尝试配置的存储渠道。未配置 R2、S3、HuggingFace、WebDAV 或 Discord 时，这些备用渠道会各自报告“未配置”。应优先查看 TelegramNew 的第一条真实错误描述。

Q5：PicGo 或 API 上传也会自动转 WebP 吗？#

不会。本方案是浏览器前端转换。直接调用 /upload 的客户端必须在客户端自行转换，或另行实现服务端编码。

Q6：上游前端更新后怎么办？#

部署补丁会验证前端 bundle 的结构。如果上游修改导致锚点不匹配，GitHub Actions 会在 Apply WebP upload customization 阶段失败。此时应更新 scripts/patch-webp-upload.mjs 和对应测试，不要简单忽略失败继续部署。

12. 推荐的日常维护流程#

1
同步上游代码
2
→ npm test
3
→ 推送 main
4
→ GitHub Actions 执行 WebP 补丁
5
→ Wrangler 部署 cloudflare-imgbed
6
→ 检查 workers.dev
7
→ 检查自定义域
8
→ 上传一张 JPG/PNG 做回归测试

只要自定义域绑定到正确 Worker，并且不存在旧 Workers Route，后续每次部署到同一个 cloudflare-imgbed 服务都会自动更新图床，无需重复配置 DNS。

Linux 家庭服务器服务编排实战

Wed, 08 Apr 2026 00:00:00 GMT

Linux 家庭服务器服务编排实战#

🐧 这篇文章关注的不是“装了什么”，而是“怎么让它长期不乱”

很多人第一次搭家庭服务器时，目标只是“服务跑起来”。但真正麻烦的不是第一次部署，而是三个月后你还敢不敢改它。

第一步：目录结构要先定#

如果一台服务器里：

配置文件到处散
数据目录位置不统一
Compose 文件一个服务一套风格

那后面排障和迁移都会很痛苦。

建议至少先统一三类目录：

apps/：服务编排文件
data/：持久化数据
logs/：日志输出

这样每加一个新服务时，你都知道它该放哪里，而不是每次重新发明结构。

第二步：服务边界不要按“软件名字”拆，而要按职责拆#

例如你想做一个家庭内容站，常见组件包括：

反向代理
面板或入口页
数据库
文件存储
媒体服务
监控服务

如果一开始就把所有东西写进一个巨大的 Compose 文件里，短期看省事，长期看非常难维护。

更稳的方式是：

网关层一组
基础设施一组
内容服务一组
监控和辅助一组

这样你以后迁移或下线某一类服务时，不会牵动整个系统。

第三步：反向代理是管理成本的关键点#

反向代理不只是为了漂亮域名，更重要的是：

统一入口
控制 HTTPS
统一鉴权前置层
降低各服务暴露复杂度

如果这层做得稳，后面无论加多少服务，外部入口都不会失控。

第四步：配置与数据一定分离#

一个常见错误是：

服务容器删掉了
配置和数据跟着一起没了

只要服务目录一复杂，这种问题迟早会出现。

所以要把：

容器定义
配置文件
数据卷
日志输出

分开看待。

能重建的是编排，不能轻易丢的是数据。

第五步：别等出问题了才做监控#

家庭服务器也要有最基础的健康检查意识。

至少要知道：

服务在不在线
端口是不是正常
反向代理是否转发成功
磁盘和内存是否接近上限

你不一定要一开始就上完整监控栈，但最基础的探针和日志入口要提前留好。

第六步：更新策略要保守#

家庭服务器最怕的不是“旧”，而是“乱更”。

建议的思路是：

基础设施慢更新
业务服务小步更新
更新前先看依赖变化
关键服务保留回滚路径

这样你的服务器会更像一套长期维护系统，而不是一个不断堆新东西的实验场。

一个推荐的演进顺序#

如果你从零开始搭，我建议顺序是：

先搭好反向代理
再搭最核心的 1 到 2 个服务
再统一目录和数据规则
最后再补监控、自动备份和辅助工具

不要一开始就十几个服务一起上，否则你很难知道问题到底在哪一层。

结语#

一台好维护的 Linux 家庭服务器，不是装得最多，而是：

边界清楚
目录统一
入口稳定
更新克制

把这些基础打好，后面加服务才会越来越轻松。

Windows 与 WSL 协同开发环境整理

Wed, 08 Apr 2026 00:00:00 GMT

Windows 与 WSL 协同开发环境整理#

🪟 适合这篇文章的人

主要用 Windows，但越来越离不开 Linux 工具链

经常在 PowerShell、Git Bash、WSL 之间切来切去

想把代码目录、工具安装和终端习惯整理统一

先统一一个原则：桌面交互归 Windows，命令行工具归 WSL#

很多混乱不是因为工具太多，而是职责没分清。

比较稳的分工方式是：

Windows 负责图形界面软件
- VS Code
- 浏览器
- 微信 / 截图 / 文件管理
WSL 负责类 Linux 命令行环境
- bash
- ssh
- grep
- sed
- git
- python / node 这类命令行工具

这样做最大的好处是：你不会再陷入“这个工具到底装在哪边”的反复摇摆。

第二步：代码目录不要到处放#

一个容易踩坑的点是：

一部分项目放在 C:
一部分项目放在 WSL 的 ~
Obsidian、Git、编辑器、脚本都在跨路径访问

建议尽量把长期维护的项目放在一个固定区，比如：

Windows 路径统一放在一个开发盘
WSL 内部只保留更适合 Linux 原生环境的项目

如果你的主要编辑器还是 Windows 端 VS Code，那么把项目统一放在 Windows 文件系统里通常更方便。

第三步：PowerShell 和 WSL 的边界要清晰#

PowerShell 很适合：

Windows 文件管理
系统设置和脚本
本地开发命令入口

WSL 更适合：

Linux 工具链
容器和服务编排
SSH 和远程服务器操作

你不需要强行只用一种终端，重点是：

同一种任务尽量固定在同一个环境里完成。

第四步：Git 的身份和凭据只保留一套主线#

如果 Windows 和 WSL 各自配一套用户名、邮箱、SSH Key，又不清楚谁在推代码，后面很容易乱。

建议你先确定：

日常提交主要从 Windows 发起，还是从 WSL 发起
哪边维护主用 Git 凭据
哪边负责 SSH / HTTPS 登录主路径

只要主线明确了，另一边就不再是“也许会用”的半配置状态。

第五步：终端体验要减少切换成本#

一个舒服的环境，不是插件越多越好，而是切换成本足够低。

你可以优先统一这些：

默认编码
常用别名
Git prompt
常见目录跳转方式
常用命令的历史习惯

这样即使你同时用 PowerShell 和 WSL，也不会感觉像在两个世界来回切换。

一个实用的落地顺序#

推荐按这个顺序整理：

先定项目目录规范
再定 Git 主用环境
再装命令行工具
最后再美化终端和补插件

顺序反过来很容易变成：终端很花，但环境依然乱。

结语#

Windows 和 WSL 不是谁替代谁，而是该分工清楚。

只要把：

图形界面
命令行环境
项目目录
Git 主线

这四件事理顺，你的开发体验就会稳定很多。

软件架构设计入门：从拆模块到定边界

Wed, 08 Apr 2026 00:00:00 GMT

软件架构设计入门：从拆模块到定边界#

🧭 本文想解决的问题

为什么很多项目不是功能难，而是越写越乱

怎么判断一个模块边界是不是合理

如何在早期就把耦合风险压下来

从一个很小的需求开始#

假设我们要做一个“个人收藏夹”系统，用户可以：

登录
收藏文章
给收藏打标签
搜索和筛选收藏内容

很多项目在这个阶段就会直接开干，把所有逻辑都堆在一个服务里。短期看很快，长期看代价很大：

登录逻辑和收藏逻辑耦在一起
搜索需求一来，数据访问层迅速变复杂
后面要加同步、分享、推荐时，改动范围会越来越大

模块划分的第一个标准：职责是否单一#

最简单的拆分方法不是按文件类型，而是按“这个模块到底负责什么”。

例如这个小系统可以先拆成：

auth：只处理身份认证和登录状态
bookmark：只处理收藏的增删改查
tag：只处理标签归类
search：只处理查询与筛选逻辑

这样拆的好处是：

你能明确每个模块的输入输出
测试会更容易写
后面重构时不容易牵一发而动全身

第二个标准：依赖方向要稳定#

一个常见错误是：

bookmark 依赖 search
search 又反过来调用 bookmark

这类双向依赖在小项目里也许能跑，但只要需求继续增长，就会让结构迅速失控。

更健康的方式是：

核心数据模块向下沉
组合逻辑向上提
搜索读取收藏数据，但不反向控制收藏模块

简单说：

底层模块提供能力，上层模块负责组织能力。

第三个标准：接口要为变化留空间#

接口设计的目标不是“现在能用”，而是“之后变化时，不必把整条链重写”。

例如收藏模块提供的接口，如果一开始就只返回最底层数据库结构，后面你想：

加排序
加推荐状态
加归档标记

就会让调用方一起跟着改。

更稳的方式是：

对外暴露语义明确的返回结构
把数据库字段和业务字段分开思考
让调用方依赖业务语义，而不是表结构细节

什么时候该继续拆，什么时候先别拆#

很多人一学架构就容易过度设计。这里有个实用判断标准：

如果一个模块已经同时满足下面两条，就值得拆：

它承担了两种以上明显不同的职责
它的变更频率和依赖方不一致

反过来，如果只是代码量多，但职责其实单一，就未必要急着拆。

一个更实用的检查清单#

你可以用下面的问题快速判断当前结构是不是健康：

这个模块一句话能不能说清楚职责？
调用它的人，是否必须知道它的内部细节？
改它时，会不会波及一大片无关功能？
这个模块的测试，是不是越来越难写？

如果这几个问题里有两个以上答不上来，就说明边界已经开始模糊了。

结语#

好的架构不是把系统拆得多漂亮，而是让系统在变化中仍然可维护。

所以真正值得先练的，不是画复杂架构图，而是把这三件事练熟：

职责划分
依赖方向
接口边界

把这三件事做好，小项目会更清晰，大项目也更容易演进。

校园网串流方案

Sat, 04 Apr 2026 00:00:00 GMT

校园网串流方案#

🌟串流核心要点 了解P2P原理和使用异地组网工具搭建内网环境使用ipv6 直连了解frp中转原理和使用中转服务器实现串流接触了解Sunshine和Moonlight工具

🤖串流软件配置#

Sunshine 基地版#

Github地址:Releases · AlkaidLab/foundation-sunshine

安装#

安装会给出许多安装组件

1
首次安装推荐所有组件都安装，非首次如图勾选

设置#

配对（pin）

1
如图所示，配对码是后面Moonlight发送过来的

1
在应用中可以配置主页，steam，游戏等页面

1
在网络设置中将UPnP打开。IP改为IPv4+IPv6;注意下面Sunshine使用的端口，在防火墙中要放行这些端口。

1
将所有加密模式设为禁用

Moonlight v+#

Github 地址：Releases · qiin2333/moonlight-vplus

在电脑端按win键，搜索cmd，回车，输入ipconfig

1
找到自己设备的ipv4地址

在局域网环境下，Moonlight中输入设备的ipv4地址，检索到设备。点击向Sunshine发送配对码，配对成功后完成基础设置

设置#

在moonlight v+里可以设置串流时的分辨率和帧数，虚拟手柄，虚拟麦克风等等。

1
在高级设置里推荐开启性能监控图层，这个HUD非常舒服，能看到网络延迟，帧数，丢包率和编解码速度，帮助你更好地排除问题。

🛜IPv6直连方案#

如果你的校园网很幸运地有ipv6地址，那么恭喜你，你可以直接通过IPv6直连。 👉 校园网 IPv6 =
免费高速公网 + 低延迟 + 可直连服务器

核心就是：

手机 / 笔记本（Moonlight）
↓（IPv6直连）
你的电脑（Sunshine）

前提条件#

✅ 1. 两端都有 IPv6#

校园网 ✔
手机：
- 流量：基本支持
- WiFi：看运营商

👉 测试：

打开 https://test-ipv6.com/

Sunshine 主机配置#

记录ipv6地址例如：

[2408:xxxx:xxxx:xxxx::1234]

1
在地址中输入主机的IPV6地址，记得在主机防火墙放行Sunshine对应端口

优化#

🚀 1. 强制走 IPv6（避免走 IPv4）#

有时候系统会优先 IPv4

👉 Windows：

Bash

1
netsh interface ipv6 set prefixpolicy ::ffff:0:0/96 10 4

👉 或直接：

在 Moonlight 只填 IPv6（推荐）

👉 校园网 IPv6：

可以直接拉高码率(根据你校园网的带宽，ipv6受到的限制较小)

🛜异地组网P2P连接#

当我们的两台设备处于不同的网络环境下，moonlight就没法实现串流，怎么解决呢，就是通过内网穿透工具ZeroTier/皎月连打孔，搭建一个虚拟网络，实现两台设备在一个虚拟的局域网内，这样moonlight就可以在同一个虚拟局域网下实现串流了

皎月连下载地址：皎月连一键内网穿透 服务端： 打开软件并登录，在左侧选择“服务端”

1.开启“组网模式”开关

2.输入6-20位页面访问密码（这个作用是限制其他组网进来的客户端访问控制页面）

3.点击左下方“开启服务”按钮，成功后按钮会变成黄色

客户端（这里以安卓举例）：

打开软件并登录

1.在左上方列表中选择一个在线主机（服务端的主机名）

2.点击下方“连接”按钮，连接成功后按钮会变成黄色（安卓端第一次使用会询问是否授权，选择“是”）

1
3.记住映射列表中的局域网ip【10.6.22.1】 按手机home键将软件后台运行

4.打开应用软件（moonlight），输入虚拟局域网ip【10.6.22.1】建立连接

注意#

有些校园网的NAT非常严格，UDP打洞几乎必然失败

1
校园网结构：

👉 对称 NAT（Symmetric NAT）

特点：

每个目标地址都会分配不同端口
外部无法“反向连接你”

🚫 二、防火墙 / 端口封锁#

校园网通常会：

❌ 禁 UDP（尤其是高端口）
❌ 限制 47984 / 47989（Moonlight常用端口）
❌ 限制外网入站连接

👉 就算 NAT 可以，端口被封也会失败

博主本人的校园网环境就属于这种，通过皎月连无法实现异地组网。但还有第三种办法

🛜使用云服务器配合 FRP进行内网穿透#

使用云服务器配合 FRP（Fast Reverse Proxy）进行内网穿透，是目前校园网环境下最稳定、成功率最高的串流方案。

整个过程分为三步：云服务器端配置（frps） -> 校园网电脑端配置（frpc） -> 连接测试。

云服务器配置#

首先，你需要准备一台云服务器，如果你是个学生，那么很幸运，你可以通过阿里云学生认证，搞到一台半年的2核2G200Mbps的服务器😁，这种性能拿来搞FRP已经是杀鸡用牛刀了。（系统选Ubuntu 即可）

购买好服务器后，进入防火墙页面，把sunshine所需要的端口全部放行

配置好后，通过ssh登上服务器（这一步自找教程）。在服务器上搭载好frp服务

去 Github 下载对应架构的 frp 压缩包,Github地址：Releases · fatedier/frp（推荐本地下载好后上传到服务器，云服务器访问github地址经常中断，换镜像站也不好使）
下载完成后，执行解压命令(这里用的是v0.58)：

Bash

Terminal window

1
tar -zxvf frp_0.58.1_linux_amd64.tar.gz

进入解压出来的文件夹：

Bash

Terminal window

1
cd frp_0.58.1_linux_amd64

确认配置文件

进入文件夹后，我们要检查一下服务端配置文件 frps.toml。新版 FRP 默认的配置文件已经帮你写好了 bindPort = 7000，完全不需要你改代码！

你可以输入下面这个命令看一眼：

Bash

Terminal window

1
cat frps.toml

如果屏幕上输出了 bindPort = 7000，说明一切完美，直接进入下一步

试运行服务

现在，我们要让服务端跑起来，测试一下之前阿里云防火墙放行的 7000 端口通没通。输入：

Bash

Terminal window

1
./frps -c ./frps.toml

成功的标志： 如果你按下回车后，屏幕上弹出了几行日志，并且最后一行写着类似 frps started successfully 或者 Run frps successfully，那么恭喜你！你的云服务器中转站已经成功启动了！

让 FRP 在后台静默运行

刚才的试运行状态下，如果你把 SSH 连接窗口关掉，FRP 就会跟着断开。为了让它 24 小时待命，我们需要把它挂在后台运行。

先在刚才的黑框里按 Ctrl + C，停掉试运行的程序。

然后，复制并执行这行“后台运行”命令：

Bash

Terminal window

1
nohup ./frps -c ./frps.toml > frps.log 2>&1 &

执行完后，屏幕可能会跳出一行提示（比如 [1] 12345），直接按一下回车键即可。 (这行命令的意思是：把 frps 放到后台静默运行，哪怕你现在关掉电脑、关掉阿里云页面，它也会一直在服务器里默默工作)

到这里，云服务器端的所有配置已经 100% 搞定了！

PC端FRP配置#

在本地下载 Windows 版 FRP(注意版本与服务器端保持一致)

解压并修改配置文件

把下载的 zip 压缩包解压到一个你常用的文件夹（比如 D 盘的某个文件夹）。

在解压出来的文件夹里，找到 frpc.toml 这个文件。

右键 -> 打开方式 -> 记事本。

把里面的内容替换成下面这段代码

Terminal window展开收起

1
serverAddr = "你的服务器公网地址"
2
serverPort = 7000
3
loginFailExit = false
4

5
[[proxies]]
6
name = "sunshine_tcp_47984"
7
type = "tcp"
8
localIP = "127.0.0.1"
9
localPort = 47984
10
remotePort = 47984
11

12
[[proxies]]
13
name = "sunshine_tcp_47989"
14
type = "tcp"
15
localIP = "127.0.0.1"
16
localPort = 47989
17
remotePort = 47989
18

19
[[proxies]]
20
name = "sunshine_tcp_47990"
21
type = "tcp"
22
localIP = "127.0.0.1"
23
localPort = 47990
24
remotePort = 47990
25

26
[[proxies]]
27
name = "sunshine_tcp_48010"
28
type = "tcp"
29
localIP = "127.0.0.1"
30
localPort = 48010
31
remotePort = 48010
32

33
[[proxies]]
34
name = "sunshine_udp_47998"
35
type = "udp"
36
localIP = "127.0.0.1"
37
localPort = 47998
38
remotePort = 47998
39

40
[[proxies]]
41
name = "sunshine_udp_47999"
42
type = "udp"
43
localIP = "127.0.0.1"
44
localPort = 47999
45
remotePort = 47999
46

47
[[proxies]]
48
name = "sunshine_udp_48000"
49
type = "udp"
50
localIP = "127.0.0.1"
51
localPort = 48000
52
remotePort = 48000

展开收起

保存，之后我们还要做一些收尾工作。

把 FRP 文件夹加入“白名单”（以 Windows 自带的 Defender 为例）#

如果你装了火绒或 360，请在它们的设置里找到“信任区/白名单”，把你frp所在的文件夹加进去。如果是 Windows 自带的安全中心：

点击电脑右下角的盾牌图标，打开 Windows 安全中心（或者在开始菜单搜“Windows 安全中心”）。
点击 “病毒和威胁防护”。
在“病毒和威胁防护设置”下，点击 “管理设置”。
往下滚动到底部，找到“排除项”，点击 “添加或删除排除项”。
点击 “添加排除项” -> 选择 “文件夹”，然后选中你的文件夹

设置FRP服务开机自启#

在你电脑随便哪个位置（比如桌面，或者你的 FRP 文件夹里），右键新建一个 文本文档 (.txt)

打开它，把下面这两行代码原封不动地复制进去（这利用了 Windows 自带的 VBS 脚本功能，作用是后台静默执行刚才那段启动代码）：

1
Set ws = CreateObject("Wscript.Shell")
2
ws.run "cmd /c cd /d "这里输入你自己的frp的文件夹的目录，记得把外面的双引号去掉" && frpc.exe -c frpc.toml", vbhide

保存文件，然后关掉记事本。
把这个文本文件的名字重命名为 start_frpc.vbs（注意：后缀名一定要从 .txt 改成 .vbs。如果你的电脑看不到后缀名，请先在文件夹顶部的“查看”里勾选“文件扩展名”）。
测试一下： 双击运行这个 start_frpc.vbs。你会发现屏幕上没有任何反应（没有黑框弹出），但如果你此时去手机上打开 Moonlight，看看能否连接！

把脚本加入“开机自启”#

现在它能隐身运行了，我们再让它开机自己启动：

按住键盘上的 Win + R 键，调出“运行”窗口。
输入 shell:startup 并按回车。
把刚才做好的那个 start_frpc.vbs 文件，剪切并粘贴到这个“启动”文件夹里。

成果#

使用中转服务器，主机连着网线的话，一般延迟是稳定在30ms左右的，当然，这也跟校园网的体质有关系。如果出现端口未转发的错误报告的话，检查一下服务器和主机的防火墙设置.Moonlight它一般会设置两个地址，一个局域网一个公网。局域网走不通会自动走公网。

如果延迟和丢包依然比较高的话，将码率降到10M以下，检查一下上行带宽是否正常。因为校园网有AP隔离和QOS策略

1
效果图

Java并发编程深度解析：从理论到实践

Mon, 20 Oct 2025 00:00:00 GMT

Java并发编程深度解析：从理论到实践#

🧵 并发编程核心要点

深入理解Java内存模型和happens-before原则

掌握synchronized、volatile、Lock等同步机制

熟练运用线程池和并发工具类

了解常见并发问题的原因和解决方案

学习高性能并发编程的最佳实践

🎯 为什么需要并发编程？#

在现代计算机系统中，CPU通常拥有多个核心，为了充分利用硬件资源，提升程序性能，我们需要让程序能够同时执行多个任务。这就是并发编程的核心价值。

并发 vs 并行#

graph LR subgraph "并发(Concurrency)" A[Task1] -.-> B[Task2] B -.-> C[Task3] C -.-> A end subgraph "并行(Parallelism)" D[Task1] E[Task2] F[Task3] end A --> G[单核CPU时间片轮转] D --> H[多核CPU同时执行]

🧠 Java内存模型 (JMM)#

内存模型基础#

graph TB subgraph "JVM内存结构" A[主内存 Main Memory] subgraph "线程1" B[工作内存1] C[本地变量副本] end subgraph "线程2" D[工作内存2] E[本地变量副本] end B <--> A D <--> A C -.-> B E -.-> D end

Happens-Before规则#

1
public class HappensBeforeExample {
2
    private int x = 0;
3
    private volatile boolean flag = false;
4

5
    // 线程1执行
6
    public void writer() {
7
        x = 42;           // 1
8
        flag = true;      // 2
9
    }
10

11
    // 线程2执行
12
    public void reader() {
13
        if (flag) {       // 3
14
            int y = x;    // 4, y的值一定是42
15
        }
16
    }
17
}

展开收起

分析：由于flag是volatile变量，操作2 happens-before 操作3，而操作1在操作2之前，操作4在操作3之后，所以操作1 happens-before 操作4。

🔐 同步机制详解#

1. synchronized关键字#

1
public class SynchronizedExample {
2
    private int count = 0;
3
    private final Object lock = new Object();
4

5
    // 同步方法
6
    public synchronized void increment1() {
7
        count++;
8
    }
9

10
    // 同步代码块 - 实例锁
11
    public void increment2() {
12
        synchronized (this) {
13
            count++;
14
        }
15
    }
16

17
    // 同步代码块 - 私有锁
18
    public void increment3() {
19
        synchronized (lock) {
20
            count++;
21
        }
22
    }
23

24
    // 静态同步方法 - 类锁
25
    public static synchronized void staticMethod() {
26
        // 静态操作
27
    }
28
}

展开收起

synchronized底层实现#

1
// 编译后的字节码（简化版）
2
public void increment() {
3
    // monitorenter  // 获取锁
4
    count++;
5
    // monitorexit   // 释放锁
6
}

2. volatile关键字#

1
public class VolatileExample {
2
    private volatile boolean running = true;
3
    private volatile int counter = 0;
4

5
    public void stop() {
6
        running = false;  // 立即对所有线程可见
7
    }
8

9
    public void run() {
10
        while (running) {
11
            // 执行任务
12
            counter++;    // 注意：volatile不保证原子性
13
        }
14
    }
15

16
    // 错误示例：volatile不能保证复合操作的原子性
17
    private volatile int volatileCount = 0;
18

19
    public void wrongIncrement() {
20
        volatileCount++;  // 这不是原子操作！包含读取、计算、写入三步
21
    }
22

23
    // 正确做法：使用AtomicInteger
24
    private final AtomicInteger atomicCount = new AtomicInteger(0);
25

26
    public void correctIncrement() {
27
        atomicCount.incrementAndGet();  // 这是原子操作
28
    }
29
}

展开收起

3. Lock接口和ReentrantLock#

1
public class LockExample {
2
    private final ReentrantLock lock = new ReentrantLock();
3
    private final Condition condition = lock.newCondition();
4
    private int count = 0;
5

6
    public void increment() {
7
        lock.lock();
8
        try {
9
            count++;
10
            condition.signalAll();  // 唤醒等待的线程
11
        } finally {
12
            lock.unlock();  // 确保在finally块中释放锁
13
        }
14
    }
15

16
    public void waitForCondition() throws InterruptedException {
17
        lock.lock();
18
        try {
19
            while (count < 10) {
20
                condition.await();  // 等待条件满足
21
            }
22
            // 条件满足后的处理逻辑
23
        } finally {
24
            lock.unlock();
25
        }
26
    }
27

28
    // 可中断的锁获取
29
    public void interruptibleLock() throws InterruptedException {
30
        if (lock.tryLock(5, TimeUnit.SECONDS)) {  // 尝试获取锁，最多等待5秒
31
            try {
32
                // 执行临界区代码
33
            } finally {
34
                lock.unlock();
35
            }
36
        } else {
37
            throw new RuntimeException("无法获取锁");
38
        }
39
    }
40
}

展开收起

ReentrantLock vs synchronized#

特性	synchronized	ReentrantLock
使用简便性	🟢 简单	🟡 需要手动管理
功能丰富性	🟡 基础功能	🟢 功能丰富
性能	🟢 JVM优化	🟡 相当
可中断性	❌ 不支持	✅ 支持
公平锁	❌ 不支持	✅ 支持
条件变量	❌ 单一wait/notify	✅ 多个Condition

🧵 线程池详解#

ThreadPoolExecutor参数解析#

1
public class ThreadPoolExample {
2

3
    public static void main(String[] args) {
4
        // 自定义线程池
5
        ThreadPoolExecutor executor = new ThreadPoolExecutor(
6
            5,                              // corePoolSize: 核心线程数
7
            10,                             // maximumPoolSize: 最大线程数
8
            60L,                            // keepAliveTime: 空闲线程存活时间
9
            TimeUnit.SECONDS,               // unit: 时间单位
10
            new ArrayBlockingQueue<>(100),  // workQueue: 任务队列
11
            new ThreadPoolExecutor.CallerRunsPolicy()  // handler: 拒绝策略
12
        );
13

14
        // 提交任务
15
        for (int i = 0; i < 20; i++) {
16
            final int taskNum = i;
17
            executor.submit(() -> {
18
                System.out.println("执行任务 " + taskNum +
19
                    " - 线程: " + Thread.currentThread().getName());
20
                try {
21
                    Thread.sleep(2000);
22
                } catch (InterruptedException e) {
23
                    Thread.currentThread().interrupt();
24
                }
25
            });
26
        }
27

28
        // 优雅关闭
29
        executor.shutdown();
30
        try {
31
            if (!executor.awaitTermination(60, TimeUnit.SECONDS)) {
32
                executor.shutdownNow();
33
            }
34
        } catch (InterruptedException e) {
35
            executor.shutdownNow();
36
        }
37
    }
38
}

展开收起

线程池执行流程#

flowchart TD A[提交任务] --> B{核心线程池是否已满?} B -->|否| C[创建核心线程执行] B -->|是| D{任务队列是否已满?} D -->|否| E[任务加入队列等待] D -->|是| F{最大线程池是否已满?} F -->|否| G[创建非核心线程执行] F -->|是| H[执行拒绝策略] C --> I[任务执行完成] E --> I G --> I

常用拒绝策略#

1
public class RejectionPolicyExample {
2

3
    // 1. CallerRunsPolicy - 调用者运行
4
    ThreadPoolExecutor executor1 = new ThreadPoolExecutor(
5
        2, 4, 60L, TimeUnit.SECONDS,
6
        new ArrayBlockingQueue<>(2),
7
        new ThreadPoolExecutor.CallerRunsPolicy()  // 主线程执行被拒绝的任务
8
    );
9

10
    // 2. AbortPolicy - 抛出异常（默认）
11
    ThreadPoolExecutor executor2 = new ThreadPoolExecutor(
12
        2, 4, 60L, TimeUnit.SECONDS,
13
        new ArrayBlockingQueue<>(2),
14
        new ThreadPoolExecutor.AbortPolicy()  // 抛出RejectedExecutionException
15
    );
16

17
    // 3. DiscardPolicy - 静默丢弃
18
    ThreadPoolExecutor executor3 = new ThreadPoolExecutor(
19
        2, 4, 60L, TimeUnit.SECONDS,
20
        new ArrayBlockingQueue<>(2),
21
        new ThreadPoolExecutor.DiscardPolicy()  // 直接丢弃任务，不抛异常
22
    );
23

24
    // 4. DiscardOldestPolicy - 丢弃最旧的
25
    ThreadPoolExecutor executor4 = new ThreadPoolExecutor(
26
        2, 4, 60L, TimeUnit.SECONDS,
27
        new ArrayBlockingQueue<>(2),
28
        new ThreadPoolExecutor.DiscardOldestPolicy()  // 丢弃队列头部最旧的任务
29
    );
30

31
    // 5. 自定义拒绝策略
32
    ThreadPoolExecutor executor5 = new ThreadPoolExecutor(
33
        2, 4, 60L, TimeUnit.SECONDS,
34
        new ArrayBlockingQueue<>(2),
35
        (task, executor) -> {
36
            // 自定义处理逻辑，如记录日志、降级处理等
37
            System.err.println("任务被拒绝: " + task.toString());
38
            // 可以选择将任务存储到数据库或消息队列中
39
        }
40
    );
41
}

展开收起

🛠️ 并发工具类#

1. CountDownLatch - 倒计时门闩#

1
public class CountDownLatchExample {
2

3
    public static void main(String[] args) throws InterruptedException {
4
        int numTasks = 3;
5
        CountDownLatch latch = new CountDownLatch(numTasks);
6

7
        // 启动多个任务
8
        for (int i = 0; i < numTasks; i++) {
9
            final int taskId = i;
10
            new Thread(() -> {
11
                try {
12
                    System.out.println("任务 " + taskId + " 开始执行");
13
                    Thread.sleep(1000 + taskId * 500);  // 模拟任务执行
14
                    System.out.println("任务 " + taskId + " 执行完成");
15
                } catch (InterruptedException e) {
16
                    Thread.currentThread().interrupt();
17
                } finally {
18
                    latch.countDown();  // 完成一个任务，计数减1
19
                }
20
            }).start();
21
        }
22

23
        // 等待所有任务完成
24
        System.out.println("等待所有任务完成...");
25
        latch.await();
26
        System.out.println("所有任务已完成！");
27
    }
28
}

展开收起

2. CyclicBarrier - 循环栅栏#

1
public class CyclicBarrierExample {
2

3
    public static void main(String[] args) {
4
        int numThreads = 3;
5

6
        CyclicBarrier barrier = new CyclicBarrier(numThreads, () -> {
7
            System.out.println("所有线程都到达栅栏，开始执行汇总操作！");
8
        });
9

10
        for (int i = 0; i < numThreads; i++) {
11
            final int threadId = i;
12
            new Thread(() -> {
13
                try {
14
                    // 第一阶段工作
15
                    System.out.println("线程 " + threadId + " 完成第一阶段工作");
16
                    Thread.sleep(1000 + threadId * 200);
17

18
                    barrier.await();  // 等待其他线程完成第一阶段
19

20
                    // 第二阶段工作
21
                    System.out.println("线程 " + threadId + " 开始第二阶段工作");
22
                    Thread.sleep(500);
23
                    System.out.println("线程 " + threadId + " 完成第二阶段工作");
24

25
                } catch (InterruptedException | BrokenBarrierException e) {
26
                    e.printStackTrace();
27
                }
28
            }).start();
29
        }
30
    }
31
}

展开收起

3. Semaphore - 信号量#

1
public class SemaphoreExample {
2
    private static final Semaphore semaphore = new Semaphore(3);  // 允许3个线程同时执行
3

4
    public static void main(String[] args) {
5
        for (int i = 0; i < 10; i++) {
6
            final int taskId = i;
7
            new Thread(() -> accessResource(taskId)).start();
8
        }
9
    }
10

11
    private static void accessResource(int taskId) {
12
        try {
13
            System.out.println("任务 " + taskId + " 等待获取许可证...");
14
            semaphore.acquire();  // 获取许可证
15

16
            System.out.println("任务 " + taskId + " 获得许可证，开始执行");
17
            Thread.sleep(2000);  // 模拟资源使用
18
            System.out.println("任务 " + taskId + " 执行完成，释放许可证");
19

20
        } catch (InterruptedException e) {
21
            Thread.currentThread().interrupt();
22
        } finally {
23
            semaphore.release();  // 释放许可证
24
        }
25
    }
26
}

展开收起

4. 原子类家族#

1
public class AtomicExample {
2

3
    // 基本类型原子类
4
    private final AtomicInteger counter = new AtomicInteger(0);
5
    private final AtomicLong longCounter = new AtomicLong(0);
6
    private final AtomicBoolean flag = new AtomicBoolean(false);
7

8
    // 数组类型原子类
9
    private final AtomicIntegerArray array = new AtomicIntegerArray(10);
10

11
    // 引用类型原子类
12
    private final AtomicReference<User> userRef = new AtomicReference<>();
13

14
    public void basicAtomicOperations() {
15
        // 基本操作
16
        int oldValue = counter.get();                    // 获取当前值
17
        int newValue = counter.incrementAndGet();        // 原子递增并返回新值
18
        boolean success = counter.compareAndSet(1, 2);   // CAS操作
19

20
        // 数组操作
21
        array.set(0, 100);                              // 设置指定位置的值
22
        int arrayValue = array.getAndIncrement(0);       // 原子递增指定位置
23

24
        // 自定义更新逻辑
25
        counter.updateAndGet(current -> current * 2);    // 当前值乘以2
26
        counter.accumulateAndGet(10, Integer::sum);      // 当前值加10
27
    }
28

29
    // 自定义原子操作
30
    public void customAtomicOperation() {
31
        AtomicReference<Node> head = new AtomicReference<>();
32

33
        // 无锁栈的push操作
34
        Node newNode = new Node("data");
35
        Node currentHead;
36
        do {
37
            currentHead = head.get();
38
            newNode.next = currentHead;
39
        } while (!head.compareAndSet(currentHead, newNode));
40
    }
41

42
    static class User {
43
        String name;
44
        int age;
45

46
        User(String name, int age) {
47
            this.name = name;
48
            this.age = age;
49
        }
50
    }
51

52
    static class Node {
53
        String data;
54
        Node next;
55

56
        Node(String data) {
57
            this.data = data;
58
        }
59
    }
60
}

展开收起

🚨 常见并发问题和解决方案#

1. 死锁问题#

1
public class DeadlockExample {
2
    private final Object lock1 = new Object();
3
    private final Object lock2 = new Object();
4

5
    // 可能发生死锁的代码
6
    public void method1() {
7
        synchronized (lock1) {
8
            System.out.println("方法1获得lock1");
9
            try { Thread.sleep(100); } catch (InterruptedException e) {}
10

11
            synchronized (lock2) {
12
                System.out.println("方法1获得lock2");
13
            }
14
        }
15
    }
16

17
    public void method2() {
18
        synchronized (lock2) {
19
            System.out.println("方法2获得lock2");
20
            try { Thread.sleep(100); } catch (InterruptedException e) {}
21

22
            synchronized (lock1) {
23
                System.out.println("方法2获得lock1");
24
            }
25
        }
26
    }
27

28
    // 解决方案1：统一获取锁的顺序
29
    public void safeMethod1() {
30
        synchronized (lock1) {
31
            synchronized (lock2) {
32
                // 业务逻辑
33
            }
34
        }
35
    }
36

37
    public void safeMethod2() {
38
        synchronized (lock1) {  // 与method1保持相同的锁顺序
39
            synchronized (lock2) {
40
                // 业务逻辑
41
            }
42
        }
43
    }
44

45
    // 解决方案2：使用tryLock设置超时
46
    private final ReentrantLock reentrantLock1 = new ReentrantLock();
47
    private final ReentrantLock reentrantLock2 = new ReentrantLock();
48

49
    public void timeoutMethod() {
50
        boolean lock1Acquired = false;
51
        boolean lock2Acquired = false;
52

53
        try {
54
            lock1Acquired = reentrantLock1.tryLock(1, TimeUnit.SECONDS);
55
            if (lock1Acquired) {
56
                lock2Acquired = reentrantLock2.tryLock(1, TimeUnit.SECONDS);
57
                if (lock2Acquired) {
58
                    // 执行业务逻辑
59
                }
60
            }
61
        } catch (InterruptedException e) {
62
            Thread.currentThread().interrupt();
63
        } finally {
64
            if (lock2Acquired) reentrantLock2.unlock();
65
            if (lock1Acquired) reentrantLock1.unlock();
66
        }
67
    }
68
}

展开收起

2. 生产者-消费者问题#

1
public class ProducerConsumerExample {
2
    private final BlockingQueue<String> queue = new ArrayBlockingQueue<>(10);
3
    private final AtomicBoolean running = new AtomicBoolean(true);
4

5
    // 生产者
6
    class Producer implements Runnable {
7
        @Override
8
        public void run() {
9
            int count = 0;
10
            while (running.get()) {
11
                try {
12
                    String item = "Item-" + count++;
13
                    queue.put(item);  // 队列满时会阻塞
14
                    System.out.println("生产: " + item);
15
                    Thread.sleep(100);
16
                } catch (InterruptedException e) {
17
                    Thread.currentThread().interrupt();
18
                    break;
19
                }
20
            }
21
        }
22
    }
23

24
    // 消费者
25
    class Consumer implements Runnable {
26
        private final String name;
27

28
        Consumer(String name) {
29
            this.name = name;
30
        }
31

32
        @Override
33
        public void run() {
34
            while (running.get() || !queue.isEmpty()) {
35
                try {
36
                    String item = queue.poll(1, TimeUnit.SECONDS);  // 超时等待
37
                    if (item != null) {
38
                        System.out.println(name + " 消费: " + item);
39
                        Thread.sleep(150);  // 模拟处理时间
40
                    }
41
                } catch (InterruptedException e) {
42
                    Thread.currentThread().interrupt();
43
                    break;
44
                }
45
            }
46
        }
47
    }
48

49
    public void start() {
50
        // 启动1个生产者和2个消费者
51
        new Thread(new Producer()).start();
52
        new Thread(new Consumer("消费者1")).start();
53
        new Thread(new Consumer("消费者2")).start();
54

55
        // 10秒后停止
56
        new Thread(() -> {
57
            try {
58
                Thread.sleep(10000);
59
                running.set(false);
60
                System.out.println("停止生产消费");
61
            } catch (InterruptedException e) {
62
                Thread.currentThread().interrupt();
63
            }
64
        }).start();
65
    }
66
}

展开收起

3. 缓存一致性问题#

1
public class CacheConsistencyExample {
2
    private final ConcurrentHashMap<String, String> cache = new ConcurrentHashMap<>();
3
    private final ReentrantReadWriteLock rwLock = new ReentrantReadWriteLock();
4

5
    // 问题版本：可能出现缓存不一致
6
    public String getValue(String key) {
7
        String value = cache.get(key);
8
        if (value == null) {
9
            // 这里可能有多个线程同时执行，造成重复计算
10
            value = expensiveOperation(key);
11
            cache.put(key, value);
12
        }
13
        return value;
14
    }
15

16
    // 解决方案1：使用读写锁
17
    public String getValueWithRWLock(String key) {
18
        // 先尝试读取
19
        rwLock.readLock().lock();
20
        try {
21
            String value = cache.get(key);
22
            if (value != null) {
23
                return value;
24
            }
25
        } finally {
26
            rwLock.readLock().unlock();
27
        }
28

29
        // 需要计算值，获取写锁
30
        rwLock.writeLock().lock();
31
        try {
32
            // 双重检查
33
            String value = cache.get(key);
34
            if (value == null) {
35
                value = expensiveOperation(key);
36
                cache.put(key, value);
37
            }
38
            return value;
39
        } finally {
40
            rwLock.writeLock().unlock();
41
        }
42
    }
43

44
    // 解决方案2：使用putIfAbsent
45
    public String getValueWithPutIfAbsent(String key) {
46
        return cache.computeIfAbsent(key, this::expensiveOperation);
47
    }
48

49
    // 解决方案3：使用Future避免重复计算
50
    private final ConcurrentHashMap<String, Future<String>> futureCache = new ConcurrentHashMap<>();
51

52
    public String getValueWithFuture(String key) throws ExecutionException, InterruptedException {
53
        Future<String> future = futureCache.get(key);
54
        if (future == null) {
55
            Callable<String> callable = () -> expensiveOperation(key);
56
            FutureTask<String> futureTask = new FutureTask<>(callable);
57
            future = futureCache.putIfAbsent(key, futureTask);
58
            if (future == null) {
59
                future = futureTask;
60
                futureTask.run();
61
            }
62
        }
63
        return future.get();
64
    }
65

66
    private String expensiveOperation(String key) {
67
        try {
68
            Thread.sleep(1000);  // 模拟耗时操作
69
            return "Value for " + key;
70
        } catch (InterruptedException e) {
71
            Thread.currentThread().interrupt();
72
            throw new RuntimeException(e);
73
        }
74
    }
75
}

展开收起

🎯 性能优化最佳实践#

1. 减少锁的粒度#

1
public class LockGranularityExample {
2

3
    // 粗粒度锁 - 不推荐
4
    private final Object lock = new Object();
5
    private int counter1 = 0;
6
    private int counter2 = 0;
7

8
    public void coarseGrainedLock() {
9
        synchronized (lock) {
10
            counter1++;
11
            counter2++;
12
            // 其他不相关的操作也被锁保护
13
        }
14
    }
15

16
    // 细粒度锁 - 推荐
17
    private final Object lock1 = new Object();
18
    private final Object lock2 = new Object();
19

20
    public void fineGrainedLock1() {
21
        synchronized (lock1) {
22
            counter1++;
23
        }
24
    }
25

26
    public void fineGrainedLock2() {
27
        synchronized (lock2) {
28
            counter2++;
29
        }
30
    }
31
}

展开收起

2. 使用无锁数据结构#

1
public class LockFreeExample {
2

3
    // 无锁队列
4
    private final ConcurrentLinkedQueue<String> lockFreeQueue = new ConcurrentLinkedQueue<>();
5

6
    // 无锁Map
7
    private final ConcurrentHashMap<String, String> lockFreeMap = new ConcurrentHashMap<>();
8

9
    // 无锁计数器
10
    private final AtomicLong lockFreeCounter = new AtomicLong(0);
11

12
    public void lockFreeOperations() {
13
        // 队列操作
14
        lockFreeQueue.offer("item");
15
        String item = lockFreeQueue.poll();
16

17
        // Map操作
18
        lockFreeMap.put("key", "value");
19
        String value = lockFreeMap.get("key");
20

21
        // 计数器操作
22
        long count = lockFreeCounter.incrementAndGet();
23
    }
24
}

展开收起

3. 合理使用ThreadLocal#

1
public class ThreadLocalExample {
2

3
    // 用于存储用户会话信息
4
    private static final ThreadLocal<UserSession> userSessionThreadLocal = new ThreadLocal<>();
5

6
    // 用于格式化日期（SimpleDateFormat不是线程安全的）
7
    private static final ThreadLocal<SimpleDateFormat> dateFormatThreadLocal =
8
        ThreadLocal.withInitial(() -> new SimpleDateFormat("yyyy-MM-dd HH:mm:ss"));
9

10
    public void setUserSession(UserSession session) {
11
        userSessionThreadLocal.set(session);
12
    }
13

14
    public UserSession getCurrentUser() {
15
        return userSessionThreadLocal.get();
16
    }
17

18
    public String formatDate(Date date) {
19
        return dateFormatThreadLocal.get().format(date);
20
    }
21

22
    // 重要：使用完毕后要清理ThreadLocal
23
    public void cleanup() {
24
        userSessionThreadLocal.remove();
25
        dateFormatThreadLocal.remove();
26
    }
27

28
    static class UserSession {
29
        String userId;
30
        String userName;
31
        // 其他会话信息
32
    }
33
}

展开收起

🔍 并发调试技巧#

1. 线程转储分析#

1
public class ThreadDumpExample {
2

3
    public static void printThreadDump() {
4
        ThreadMXBean threadBean = ManagementFactory.getThreadMXBean();
5
        ThreadInfo[] threadInfos = threadBean.dumpAllThreads(true, true);
6

7
        for (ThreadInfo threadInfo : threadInfos) {
8
            System.out.println("线程名: " + threadInfo.getThreadName());
9
            System.out.println("线程状态: " + threadInfo.getThreadState());
10

11
            if (threadInfo.getLockName() != null) {
12
                System.out.println("等待锁: " + threadInfo.getLockName());
13
            }
14

15
            StackTraceElement[] stackTrace = threadInfo.getStackTrace();
16
            for (StackTraceElement element : stackTrace) {
17
                System.out.println("\t" + element);
18
            }
19
            System.out.println();
20
        }
21
    }
22
}

展开收起

2. 并发测试工具#

1
public class ConcurrencyTestExample {
2
    private final AtomicInteger counter = new AtomicInteger(0);
3

4
    @Test
5
    public void testConcurrentIncrement() throws InterruptedException {
6
        int threadCount = 100;
7
        int operationsPerThread = 1000;
8
        CountDownLatch latch = new CountDownLatch(threadCount);
9

10
        for (int i = 0; i < threadCount; i++) {
11
            new Thread(() -> {
12
                try {
13
                    for (int j = 0; j < operationsPerThread; j++) {
14
                        counter.incrementAndGet();
15
                    }
16
                } finally {
17
                    latch.countDown();
18
                }
19
            }).start();
20
        }
21

22
        latch.await();
23

24
        // 验证结果
25
        int expected = threadCount * operationsPerThread;
26
        assertEquals(expected, counter.get());
27
    }
28
}

展开收起

🚀 总结与最佳实践#

并发编程金律#

优先使用并发工具类：ConcurrentHashMap > synchronized HashMap
减少锁的范围：只锁必要的代码块
避免嵌套锁：防止死锁发生
使用不可变对象：天然线程安全
合理使用线程池：避免频繁创建销毁线程

性能优化checklist#

✅ 使用合适的并发工具类
✅ 减少锁的竞争和粒度
✅ 避免不必要的同步
✅ 合理设置线程池参数
✅ 及时释放资源（如ThreadLocal）

常见误区#

❌ 过度使用synchronized
❌ 忽略volatile的非原子性
❌ ThreadLocal内存泄漏
❌ 不合理的线程池配置

💡 记住：并发编程是一门艺术，需要在正确性、性能和复杂度之间找到平衡点。

📖 延伸阅读#

如果这篇文章对你有帮助，欢迎点赞分享！ ⭐

MySQL索引优化完全指南：从原理到实战

Mon, 15 Sep 2025 00:00:00 GMT

MySQL索引优化完全指南：从原理到实战#

🗃️ 核心知识点

理解B+树索引的底层原理

掌握索引设计的黄金法则

学会分析和优化慢查询

避免常见的索引失效场景

📚 什么是索引？#

索引是数据库中用于加速数据检索的数据结构，类似于书籍的目录。没有索引时，数据库需要全表扫描；有了索引，可以快速定位数据。

🌲 B+树索引原理#

为什么选择B+树？#

数据结构	查询复杂度	范围查询	磁盘IO
哈希表	O(1)	❌ 不支持	较少
二叉树	O(log n)	✅ 支持	较多
B+树	O(log n)	✅ 支持	最少

B+树结构示意#

1
                    [根节点: 50]
2
                   /            \
3
          [20, 35]              [70, 85]
4
         /    |    \           /    |    \
5
      [10,15] [25,30] [40,45] [60,65] [75,80] [90,95]
6
         ↓       ↓       ↓       ↓       ↓       ↓
7
       数据    数据    数据    数据    数据    数据
8

9
       叶子节点通过双向链表相连，支持范围查询

🎯 索引类型详解#

1. 主键索引 (Primary Key)#

1
-- 创建表时定义主键
2
CREATE TABLE users (
3
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
4
    username VARCHAR(50) NOT NULL,
5
    email VARCHAR(100) NOT NULL
6
);
7

8
-- InnoDB中，主键索引即聚簇索引，数据存储在叶子节点

2. 唯一索引 (Unique Index)#

1
-- 保证列值唯一
2
CREATE UNIQUE INDEX idx_email ON users(email);
3

4
-- 或在创建表时定义
5
CREATE TABLE users (
6
    id BIGINT PRIMARY KEY,
7
    email VARCHAR(100) UNIQUE
8
);

3. 普通索引 (Normal Index)#

1
-- 最基本的索引类型
2
CREATE INDEX idx_username ON users(username);

4. 联合索引 (Composite Index)#

1
-- 多列组合索引，遵循最左前缀原则
2
CREATE INDEX idx_name_age_city ON users(name, age, city);
3

4
-- ✅ 能使用索引的查询
5
SELECT * FROM users WHERE name = '张三';
6
SELECT * FROM users WHERE name = '张三' AND age = 25;
7
SELECT * FROM users WHERE name = '张三' AND age = 25 AND city = '北京';
8

9
-- ❌ 无法使用索引的查询
10
SELECT * FROM users WHERE age = 25;  -- 跳过了name
11
SELECT * FROM users WHERE city = '北京';  -- 跳过了name和age

5. 覆盖索引 (Covering Index)#

1
-- 当查询的列都在索引中时，无需回表
2
CREATE INDEX idx_name_email ON users(name, email);
3

4
-- ✅ 覆盖索引，不需要回表
5
SELECT name, email FROM users WHERE name = '张三';
6

7
-- ❌ 需要回表获取其他列
8
SELECT * FROM users WHERE name = '张三';

🔧 EXPLAIN分析查询#

1
EXPLAIN SELECT * FROM orders WHERE user_id = 100 AND status = 'paid';

EXPLAIN关键字段解读#

字段	说明	优化目标
type	访问类型	system > const > eq_ref > ref > range > index > ALL
key	实际使用的索引	应该使用预期的索引
rows	预估扫描行数	越小越好
Extra	额外信息	避免Using filesort, Using temporary

type类型详解#

1
-- const: 主键或唯一索引的等值查询
2
EXPLAIN SELECT * FROM users WHERE id = 1;
3

4
-- ref: 普通索引的等值查询
5
EXPLAIN SELECT * FROM users WHERE username = 'admin';
6

7
-- range: 范围查询
8
EXPLAIN SELECT * FROM users WHERE age BETWEEN 20 AND 30;
9

10
-- ALL: 全表扫描（需要优化！）
11
EXPLAIN SELECT * FROM users WHERE age + 1 = 25;

⚠️ 索引失效的常见场景#

1. 对索引列使用函数#

1
-- ❌ 索引失效
2
SELECT * FROM users WHERE YEAR(create_time) = 2024;
3

4
-- ✅ 优化后
5
SELECT * FROM users WHERE create_time >= '2024-01-01' AND create_time < '2025-01-01';

2. 隐式类型转换#

1
-- 假设 phone 是 VARCHAR 类型
2
-- ❌ 索引失效（数字与字符串比较）
3
SELECT * FROM users WHERE phone = 13800138000;
4

5
-- ✅ 正确写法
6
SELECT * FROM users WHERE phone = '13800138000';

3. LIKE以通配符开头#

1
-- ❌ 索引失效
2
SELECT * FROM users WHERE name LIKE '%张';
3

4
-- ✅ 可以使用索引
5
SELECT * FROM users WHERE name LIKE '张%';

4. OR条件未全部建立索引#

1
-- 假设只有name有索引，age没有
2
-- ❌ 索引失效
3
SELECT * FROM users WHERE name = '张三' OR age = 25;
4

5
-- ✅ 解决方案1：给age也建索引
6
-- ✅ 解决方案2：改用UNION
7
SELECT * FROM users WHERE name = '张三'
8
UNION
9
SELECT * FROM users WHERE age = 25;

5. 不等于操作#

1
-- ❌ 可能不走索引
2
SELECT * FROM users WHERE status != 'deleted';
3

4
-- ✅ 如果非删除数据占大多数，可以改写
5
SELECT * FROM users WHERE status IN ('active', 'pending', 'blocked');

💡 索引设计最佳实践#

1. 选择性高的列优先#

1
-- 选择性 = 不重复值数量 / 总行数
2
SELECT
3
    COUNT(DISTINCT status) / COUNT(*) AS status_selectivity,
4
    COUNT(DISTINCT user_id) / COUNT(*) AS user_id_selectivity
5
FROM orders;
6

7
-- user_id选择性更高，应该放在联合索引前面
8
CREATE INDEX idx_user_status ON orders(user_id, status);

2. 频繁查询的列建索引#

1
-- 分析慢查询日志，找出高频查询条件
2
-- 为WHERE、JOIN、ORDER BY、GROUP BY涉及的列建索引

3. 控制索引数量#

1
-- ❌ 索引过多会影响写入性能
2
CREATE INDEX idx_a ON table(a);
3
CREATE INDEX idx_b ON table(b);
4
CREATE INDEX idx_c ON table(c);
5
CREATE INDEX idx_ab ON table(a, b);
6
CREATE INDEX idx_bc ON table(b, c);
7

8
-- ✅ 合理设计联合索引，一个索引覆盖多个查询场景
9
CREATE INDEX idx_abc ON table(a, b, c);

4. 长字符串使用前缀索引#

1
-- 对于长字符串，使用前缀索引节省空间
2
CREATE INDEX idx_email_prefix ON users(email(10));
3

4
-- 选择合适的前缀长度
5
SELECT
6
    COUNT(DISTINCT LEFT(email, 5)) / COUNT(*) AS len5,
7
    COUNT(DISTINCT LEFT(email, 10)) / COUNT(*) AS len10,
8
    COUNT(DISTINCT LEFT(email, 15)) / COUNT(*) AS len15
9
FROM users;

📊 实战案例：电商订单表优化#

原始表结构#

1
CREATE TABLE orders (
2
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
3
    order_no VARCHAR(32) NOT NULL,
4
    user_id BIGINT NOT NULL,
5
    product_id BIGINT NOT NULL,
6
    amount DECIMAL(10,2) NOT NULL,
7
    status TINYINT NOT NULL DEFAULT 0,
8
    create_time DATETIME NOT NULL,
9
    update_time DATETIME NOT NULL
10
);

常见查询场景分析#

1
-- 场景1：根据订单号查询（高频，需要快速定位）
2
SELECT * FROM orders WHERE order_no = 'ORD202412010001';
3
-- 建议：唯一索引
4
CREATE UNIQUE INDEX idx_order_no ON orders(order_no);
5

6
-- 场景2：查询用户的订单列表（高频）
7
SELECT * FROM orders WHERE user_id = 100 ORDER BY create_time DESC;
8
-- 建议：联合索引
9
CREATE INDEX idx_user_time ON orders(user_id, create_time DESC);
10

11
-- 场景3：后台查询某状态的订单（中频）
12
SELECT * FROM orders WHERE status = 1 AND create_time > '2024-12-01';
13
-- 建议：联合索引
14
CREATE INDEX idx_status_time ON orders(status, create_time);
15

16
-- 场景4：统计某商品的销售额
17
SELECT SUM(amount) FROM orders WHERE product_id = 500 AND status = 2;
18
-- 建议：联合索引 + 覆盖索引
19
CREATE INDEX idx_product_status_amount ON orders(product_id, status, amount);

展开收起

最终索引设计#

1
-- 精简后的索引方案
2
CREATE UNIQUE INDEX idx_order_no ON orders(order_no);
3
CREATE INDEX idx_user_time ON orders(user_id, create_time DESC);
4
CREATE INDEX idx_status_time ON orders(status, create_time);
5
CREATE INDEX idx_product_status ON orders(product_id, status);

🔍 慢查询优化流程#

1
1. 开启慢查询日志
2
   ↓
3
2. 分析慢查询日志，找出问题SQL
4
   ↓
5
3. 使用EXPLAIN分析执行计划
6
   ↓
7
4. 检查是否缺少索引或索引失效
8
   ↓
9
5. 优化SQL或添加/调整索引
10
   ↓
11
6. 测试验证优化效果

开启慢查询日志#

1
-- 查看当前配置
2
SHOW VARIABLES LIKE 'slow_query%';
3
SHOW VARIABLES LIKE 'long_query_time';
4

5
-- 开启慢查询日志
6
SET GLOBAL slow_query_log = 'ON';
7
SET GLOBAL long_query_time = 1;  -- 超过1秒的查询记录

🚀 总结#

索引优化口诀#

最左前缀要牢记，联合索引按顺序
覆盖索引减回表，查询效率大提升
函数运算要避免，索引列保持原样
类型转换是大坑，字段类型要匹配
选择性高放前面，区分度大更有效

性能优化checklist#

✅ 为高频查询条件建立索引
✅ 使用EXPLAIN验证索引使用情况
✅ 避免索引失效的写法
✅ 定期分析和优化慢查询
✅ 控制单表索引数量（建议不超过5-6个）

如果这篇文章对你有帮助，欢迎点赞分享！ 💪

Git工作流与团队协作最佳实践

Sun, 10 Aug 2025 00:00:00 GMT

Git工作流与团队协作最佳实践#

🔀 你将学到

Git核心概念和常用命令

主流Git工作流对比与选择

代码审查与合并策略

解决冲突的技巧

🎯 Git基础回顾#

核心概念图解#

1
工作区(Working Directory)
2
    ↓ git add
3
暂存区(Staging Area)
4
    ↓ git commit
5
本地仓库(Local Repository)
6
    ↓ git push
7
远程仓库(Remote Repository)

常用命令速查#

Terminal window展开收起

1
# 初始化与克隆
2
git init                      # 初始化仓库
3
git clone <url>               # 克隆远程仓库
4

5
# 日常操作
6
git status                    # 查看状态
7
git add .                     # 添加所有修改到暂存区
8
git commit -m "message"       # 提交
9
git push origin main          # 推送到远程
10

11
# 分支操作
12
git branch                    # 查看分支
13
git branch feature-x          # 创建分支
14
git checkout feature-x        # 切换分支
15
git checkout -b feature-x     # 创建并切换分支
16
git merge feature-x           # 合并分支
17
git branch -d feature-x       # 删除分支
18

19
# 查看历史
20
git log --oneline --graph     # 图形化查看提交历史
21
git diff                      # 查看修改内容
22
git blame <file>              # 查看文件每行的修改者
23

24
# 撤销操作
25
git checkout -- <file>        # 撤销工作区修改
26
git reset HEAD <file>         # 取消暂存
27
git reset --soft HEAD~1       # 撤销上次提交(保留修改)
28
git reset --hard HEAD~1       # 撤销上次提交(丢弃修改)
29
git revert <commit>           # 创建一个撤销提交
30

31
# 储藏
32
git stash                     # 储藏当前修改
33
git stash pop                 # 恢复储藏
34
git stash list                # 查看储藏列表

展开收起

🔄 主流Git工作流#

1. Git Flow#

适用于发布周期固定的项目。

1
main ─────●───────────────●─────────────●──────→
2
          │               ↑             ↑
3
          │    ┌──────────┘   ┌─────────┘
4
          ↓    │              │
5
develop ──●────●────●────●────●────●────●──────→
6
               │    ↑    │         ↑
7
               │    │    │         │
8
feature/a ─────●────┘    │         │
9
                         │         │
10
feature/b ───────────────●─────────┘

分支说明：

main: 生产环境代码
develop: 开发主分支
feature/*: 功能分支
release/*: 发布分支
hotfix/*: 紧急修复分支

Terminal window展开收起

1
# Git Flow 工作流程示例
2
# 1. 开始新功能
3
git checkout develop
4
git checkout -b feature/user-login
5

6
# 2. 开发完成后合并
7
git checkout develop
8
git merge --no-ff feature/user-login
9
git branch -d feature/user-login
10

11
# 3. 准备发布
12
git checkout -b release/v1.0.0
13
# 进行发布前测试和修复
14

15
# 4. 发布
16
git checkout main
17
git merge --no-ff release/v1.0.0
18
git tag -a v1.0.0 -m "Release v1.0.0"
19

20
git checkout develop
21
git merge --no-ff release/v1.0.0
22
git branch -d release/v1.0.0

展开收起

2. GitHub Flow#

适用于持续部署的项目，简单高效。

1
main ─────●───────●───────●───────●───────→
2
          │       ↑       │       ↑
3
          │       │       │       │
4
feature ──●───●───┘       │       │
5
                          │       │
6
bugfix ───────────────────●───●───┘

流程：

从main创建分支
开发并提交
创建Pull Request
代码审查
合并到main并部署

Terminal window展开收起

1
# GitHub Flow 示例
2
# 1. 创建功能分支
3
git checkout main
4
git pull origin main
5
git checkout -b feature/shopping-cart
6

7
# 2. 开发提交
8
git add .
9
git commit -m "feat: add shopping cart functionality"
10
git push origin feature/shopping-cart
11

12
# 3. 在GitHub上创建PR，通过审查后合并
13
# 4. 删除功能分支
14
git checkout main
15
git pull origin main
16
git branch -d feature/shopping-cart

展开收起

3. Trunk-Based Development#

适用于高度自动化测试的团队。

1
main ─────●───●───●───●───●───●───●───────→
2
          │   │   │   │   │   │   │
3
         短期分支(小时级别)

特点：

所有开发者直接向main提交
分支生命周期很短（几小时到1天）
依赖Feature Flag控制功能发布

📝 Commit Message规范#

Conventional Commits格式#

1
<type>(<scope>): <subject>
2

3
<body>
4

5
<footer>

Type类型#

类型	说明	示例
`feat`	新功能	feat: 添加用户注册功能
`fix`	Bug修复	fix: 修复登录验证码失效问题
`docs`	文档更新	docs: 更新API文档
`style`	代码格式	style: 格式化代码
`refactor`	重构	refactor: 重构用户模块
`perf`	性能优化	perf: 优化首页加载速度
`test`	测试	test: 添加单元测试
`chore`	构建/工具	chore: 更新依赖版本

示例#

Terminal window

1
# 好的提交信息
2
git commit -m "feat(auth): 添加JWT token刷新机制
3

4
- 实现token自动刷新
5
- 添加token过期前5分钟自动续期
6
- 修改登录接口返回refresh_token
7

8
Closes #123"
9

10
# 不好的提交信息
11
git commit -m "修改了一些代码"
12
git commit -m "update"
13
git commit -m "fix bug"

🔀 合并策略#

1. Merge Commit#

Terminal window

1
git checkout main
2
git merge --no-ff feature/xxx

1
      A---B---C  feature
2
     /         \
3
D---E-----------F  main (merge commit)

优点：保留完整历史，可追溯缺点：历史记录较多

2. Squash Merge#

Terminal window

1
git checkout main
2
git merge --squash feature/xxx
3
git commit -m "feat: add new feature"

1
A---B---C  feature
2

3
D---E---F  main (squash成一个提交)

优点：历史简洁缺点：丢失详细提交记录

3. Rebase#

Terminal window

1
git checkout feature/xxx
2
git rebase main
3
git checkout main
4
git merge feature/xxx

1
      A---B---C  feature (before rebase)
2

3
D---E---A'---B'---C'  main (after rebase + merge)

优点：线性历史，整洁缺点：改写历史，需谨慎使用

⚔️ 解决冲突#

冲突示例#

1
<<<<<<< HEAD
2
console.log("这是main分支的代码");
3
=======
4
console.log("这是feature分支的代码");
5
>>>>>>> feature/xxx

解决步骤#

Terminal window

1
# 1. 拉取最新代码
2
git fetch origin
3
git checkout feature/xxx
4
git rebase origin/main
5

6
# 2. 出现冲突时，手动编辑文件解决
7
# 3. 标记冲突已解决
8
git add <conflicted-file>
9

10
# 4. 继续rebase
11
git rebase --continue
12

13
# 5. 如果想放弃
14
git rebase --abort

使用VS Code解决冲突#

VS Code提供了直观的冲突解决界面：

Accept Current Change: 保留当前分支修改
Accept Incoming Change: 使用合并进来的修改
Accept Both Changes: 保留两者
Compare Changes: 对比查看差异

🛡️ 代码审查最佳实践#

PR/MR检查清单#

✅ 代码符合编码规范
✅ 有足够的测试覆盖
✅ 没有敏感信息泄露
✅ 性能影响已评估
✅ 文档已更新
✅ Commit message规范

审查者要点#

1
## 审查重点
2

3
1. **功能正确性**: 代码是否实现了预期功能？
4
2. **代码质量**: 是否遵循设计原则？有无代码异味？
5
3. **安全性**: 是否存在安全漏洞？
6
4. **性能**: 是否有性能问题？
7
5. **可维护性**: 代码是否易于理解和维护？
8
6. **测试**: 测试是否充分？

🚀 实用技巧#

1. 交互式Rebase整理提交#

Terminal window

1
# 整理最近3次提交
2
git rebase -i HEAD~3
3

4
# 在编辑器中可以：
5
# pick - 保留提交
6
# squash - 合并到上一个提交
7
# reword - 修改提交信息
8
# drop - 删除提交

2. Cherry-pick选择性合并#

Terminal window

1
# 将某个提交应用到当前分支
2
git cherry-pick <commit-hash>
3

4
# 应用多个提交
5
git cherry-pick <commit1> <commit2>

3. Bisect二分查找Bug#

Terminal window

1
# 开始二分查找
2
git bisect start
3

4
# 标记当前版本有bug
5
git bisect bad
6

7
# 标记某个版本正常
8
git bisect good v1.0.0
9

10
# Git会自动检出中间版本，测试后标记good/bad
11
# 直到找到引入bug的提交
12

13
# 结束
14
git bisect reset

4. 配置别名提高效率#

Terminal window

1
# 在 ~/.gitconfig 添加
2
[alias]
3
    st = status
4
    co = checkout
5
    br = branch
6
    cm = commit -m
7
    lg = log --oneline --graph --decorate
8
    unstage = reset HEAD --
9
    last = log -1 HEAD
10
    visual = !gitk

📊 团队协作规范模板#

1
# Git协作规范
2

3
## 分支命名
4
- 功能分支: feature/功能名称
5
- 修复分支: fix/问题描述
6
- 热修复: hotfix/问题描述
7

8
## 提交规范
9
- 使用Conventional Commits格式
10
- 每个提交应该是原子性的
11
- 禁止提交未完成的代码到主分支
12

13
## 代码审查
14
- 所有代码必须经过至少1人审查
15
- 审查通过后才能合并
16
- 合并前需要通过CI检查
17

18
## 发布流程
19
1. 创建release分支
20
2. 测试验证
21
3. 合并到main并打tag
22
4. 同步到develop

展开收起

掌握Git，让团队协作更高效！ 🎉

前端性能优化实战：从加载到渲染全面提速

Sat, 05 Jul 2025 00:00:00 GMT

前端性能优化实战：从加载到渲染全面提速#

⚡ 性能优化核心目标

首屏加载时间 < 2秒

可交互时间 (TTI) < 3秒

页面流畅度 60fps

📊 性能指标解读#

Core Web Vitals#

指标	说明	优秀标准
LCP	最大内容绘制	< 2.5s
FID	首次输入延迟	< 100ms
CLS	累计布局偏移	< 0.1

🚀 资源加载优化#

1. 图片优化#

1
<!-- 使用WebP格式 -->
2
<picture>
3
  <source srcset="image.webp" type="image/webp">
4
  <source srcset="image.jpg" type="image/jpeg">
5
  <img src="image.jpg" alt="描述">
6
</picture>
7

8
<!-- 响应式图片 -->
9
<img
10
  srcset="small.jpg 480w, medium.jpg 800w, large.jpg 1200w"
11
  sizes="(max-width: 600px) 480px, (max-width: 1000px) 800px, 1200px"
12
  src="large.jpg"
13
  alt="响应式图片"
14
>
15

16
<!-- 懒加载 -->
17
<img src="placeholder.jpg" data-src="real-image.jpg" loading="lazy" alt="懒加载图片">

展开收起

2. JavaScript优化#

1
<!-- 异步加载非关键脚本 -->
2
<script src="analytics.js" async></script>
3

4
<!-- 延迟加载 -->
5
<script src="non-critical.js" defer></script>
6

7
<!-- 预加载关键资源 -->
8
<link rel="preload" href="critical.js" as="script">
9
<link rel="preload" href="font.woff2" as="font" type="font/woff2" crossorigin>

3. CSS优化#

1
<!-- 关键CSS内联 -->
2
<style>
3
  /* 首屏关键样式 */
4
  .header { ... }
5
  .hero { ... }
6
</style>
7

8
<!-- 非关键CSS异步加载 -->
9
<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
10
<noscript><link rel="stylesheet" href="styles.css"></noscript>

📦 代码分割与懒加载#

Webpack代码分割#

webpack.config.js展开收起

1
module.exports = {
2
  optimization: {
3
    splitChunks: {
4
      chunks: 'all',
5
      cacheGroups: {
6
        vendors: {
7
          test: /[\\/]node_modules[\\/]/,
8
          name: 'vendors',
9
          chunks: 'all',
10
        },
11
        common: {
12
          minChunks: 2,
13
          name: 'common',
14
          chunks: 'all',
15
        },
16
      },
17
    },
18
  },
19
};

展开收起

React懒加载#

1
import React, { Suspense, lazy } from 'react';
2

3
// 路由懒加载
4
const Home = lazy(() => import('./pages/Home'));
5
const About = lazy(() => import('./pages/About'));
6
const Dashboard = lazy(() => import('./pages/Dashboard'));
7

8
function App() {
9
  return (
10
    <Suspense fallback={<Loading />}>
11
      <Routes>
12
        <Route path="/" element={<Home />} />
13
        <Route path="/about" element={<About />} />
14
        <Route path="/dashboard" element={<Dashboard />} />
15
      </Routes>
16
    </Suspense>
17
  );
18
}

展开收起

Vue懒加载#

1
// Vue Router
2
const routes = [
3
  {
4
    path: '/dashboard',
5
    component: () => import(/* webpackChunkName: "dashboard" */ './views/Dashboard.vue')
6
  }
7
];
8

9
// 组件懒加载
10
export default {
11
  components: {
12
    HeavyComponent: () => import('./HeavyComponent.vue')
13
  }
14
};

🗜️ 资源压缩#

Gzip/Brotli压缩#

1
# Nginx配置
2
gzip on;
3
gzip_types text/plain text/css application/json application/javascript text/xml;
4
gzip_min_length 1000;
5

6
# Brotli压缩（更高压缩率）
7
brotli on;
8
brotli_types text/plain text/css application/json application/javascript;

图片压缩配置#

1
// webpack配置
2
const ImageMinimizerPlugin = require('image-minimizer-webpack-plugin');
3

4
module.exports = {
5
  plugins: [
6
    new ImageMinimizerPlugin({
7
      minimizer: {
8
        implementation: ImageMinimizerPlugin.imageminMinify,
9
        options: {
10
          plugins: [
11
            ['mozjpeg', { quality: 80 }],
12
            ['pngquant', { quality: [0.6, 0.8] }],
13
            ['svgo', { plugins: [{ removeViewBox: false }] }],
14
          ],
15
        },
16
      },
17
    }),
18
  ],
19
};

展开收起

💾 缓存策略#

HTTP缓存#

1
# Nginx缓存配置
2
location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff2)$ {
3
    expires 1y;
4
    add_header Cache-Control "public, immutable";
5
}
6

7
location ~* \.html$ {
8
    expires -1;
9
    add_header Cache-Control "no-cache, no-store, must-revalidate";
10
}

Service Worker缓存#

sw.js展开收起

1
const CACHE_NAME = 'v1';
2
const urlsToCache = [
3
  '/',
4
  '/styles/main.css',
5
  '/scripts/main.js',
6
];
7

8
// 安装
9
self.addEventListener('install', event => {
10
  event.waitUntil(
11
    caches.open(CACHE_NAME)
12
      .then(cache => cache.addAll(urlsToCache))
13
  );
14
});
15

16
// 请求拦截
17
self.addEventListener('fetch', event => {
18
  event.respondWith(
19
    caches.match(event.request)
20
      .then(response => {
21
        if (response) {
22
          return response; // 返回缓存
23
        }
24
        return fetch(event.request); // 请求网络
25
      })
26
  );
27
});

展开收起

🎨 渲染性能优化#

避免强制同步布局#

1
// ❌ 强制同步布局
2
elements.forEach(el => {
3
  const width = el.offsetWidth; // 读取
4
  el.style.width = width + 10 + 'px'; // 写入 -> 触发重排
5
});
6

7
// ✅ 批量读取后批量写入
8
const widths = elements.map(el => el.offsetWidth); // 批量读取
9
elements.forEach((el, i) => {
10
  el.style.width = widths[i] + 10 + 'px'; // 批量写入
11
});

使用CSS动画代替JS#

1
/* ✅ 使用CSS transform动画 */
2
.box {
3
  transition: transform 0.3s ease;
4
}
5
.box:hover {
6
  transform: translateX(100px);
7
}
8

9
/* ✅ 使用will-change提示浏览器 */
10
.animated-element {
11
  will-change: transform, opacity;
12
}

虚拟列表#

1
// React虚拟列表示例
2
import { FixedSizeList } from 'react-window';
3

4
function VirtualList({ items }) {
5
  const Row = ({ index, style }) => (
6
    <div style={style}>
7
      {items[index].name}
8
    </div>
9
  );
10

11
  return (
12
    <FixedSizeList
13
      height={400}
14
      itemCount={items.length}
15
      itemSize={50}
16
      width="100%"
17
    >
18
      {Row}
19
    </FixedSizeList>
20
  );
21
}

展开收起

📱 移动端优化#

触摸响应优化#

1
/* 禁用点击延迟 */
2
html {
3
  touch-action: manipulation;
4
}
5

6
/* 优化滚动 */
7
.scroll-container {
8
  -webkit-overflow-scrolling: touch;
9
  overflow-y: scroll;
10
}

骨架屏#

1
function SkeletonCard() {
2
  return (
3
    <div className="skeleton-card">
4
      <div className="skeleton-image animate-pulse"></div>
5
      <div className="skeleton-title animate-pulse"></div>
6
      <div className="skeleton-text animate-pulse"></div>
7
    </div>
8
  );
9
}
10

11
function ProductList({ loading, products }) {
12
  if (loading) {
13
    return Array(6).fill(0).map((_, i) => <SkeletonCard key={i} />);
14
  }
15
  return products.map(p => <ProductCard key={p.id} product={p} />);
16
}

展开收起

📈 性能监控#

Performance API#

1
// 页面加载性能
2
window.addEventListener('load', () => {
3
  const timing = performance.timing;
4
  const metrics = {
5
    // DNS查询时间
6
    dns: timing.domainLookupEnd - timing.domainLookupStart,
7
    // TCP连接时间
8
    tcp: timing.connectEnd - timing.connectStart,
9
    // 首字节时间
10
    ttfb: timing.responseStart - timing.requestStart,
11
    // DOM解析时间
12
    domParse: timing.domContentLoadedEventEnd - timing.domLoading,
13
    // 页面完全加载时间
14
    loadTime: timing.loadEventEnd - timing.navigationStart,
15
  };
16
  console.log(metrics);
17
  // 上报到监控系统
18
});
19

20
// 监控LCP
21
new PerformanceObserver((entryList) => {
22
  const entries = entryList.getEntries();
23
  const lastEntry = entries[entries.length - 1];
24
  console.log('LCP:', lastEntry.startTime);
25
}).observe({ entryTypes: ['largest-contentful-paint'] });

展开收起

Web Vitals监控#

1
import { getCLS, getFID, getLCP } from 'web-vitals';
2

3
function sendToAnalytics(metric) {
4
  const body = JSON.stringify(metric);
5
  navigator.sendBeacon('/analytics', body);
6
}
7

8
getCLS(sendToAnalytics);
9
getFID(sendToAnalytics);
10
getLCP(sendToAnalytics);

✅ 性能优化检查清单#

加载优化#

开启Gzip/Brotli压缩
图片使用WebP格式
实现图片懒加载
代码分割和按需加载
使用CDN加速

缓存优化#

配置合理的HTTP缓存
使用Service Worker
静态资源添加hash

渲染优化#

减少DOM操作
使用CSS动画
长列表虚拟化
避免强制同步布局

代码优化#

Tree Shaking
代码压缩混淆
移除未使用代码

性能优化是一个持续的过程，让我们一起追求极致体验！ 🚀

Spring框架依赖注入深度解析：从XML到注解的演进之路

Wed, 28 May 2025 00:00:00 GMT

Spring框架依赖注入深度解析：从XML到注解的演进之路#

🌟 核心要点预览

理解IoC容器的本质和作用

掌握依赖注入的三种实现方式

对比XML配置与注解配置的优劣

学习Spring Boot的自动配置原理

探索现代Spring开发最佳实践

🎯 什么是依赖注入？为什么需要它？#

在讨论注解，xml之前，我们先回归spring最核心，也是最重要的概念——容器。容器，顾名思义，为某种特定组件的运行提供必要支持的一个软件环境。在java开发中，组件的耦合依赖是常有之事。举个例子，参考廖雪峰老师的教程（知乎号：(廖雪峰 - 知乎）

我们假定一个在线书店，通过BookService获取书籍：

1
public class BookService {
2
    private HikariConfig config = new HikariConfig();
3
    private DataSource dataSource = new HikariDataSource(config);
4

5
    public Book getBook(long bookId) {
6
        try (Connection conn = dataSource.getConnection()) {
7
            ...
8
            return book;
9
        }
10
    }
11
}

为了实例化一个HikariDataSource，我们不得不实例化一个HikariConfig。而要实例化这个HikariConfig，我们必须要熟知它的配置

现在，我们继续编写UserService获取用户：

1
public class UserService {
2
    private HikariConfig config = new HikariConfig();
3
    private DataSource dataSource = new HikariDataSource(config);
4

5
    public User getUser(long userId) {
6
        try (Connection conn = dataSource.getConnection()) {
7
            ...
8
            return user;
9
        }
10
    }
11
}

因为UserService也需要访问数据库，因此，我们不得不也实例化一个HikariDataSource。

在处理用户购买的CartServlet中，我们需要实例化UserService和BookService：

1
public class CartServlet extends HttpServlet {
2
    private BookService bookService = new BookService();
3
    private UserService userService = new UserService();
4

5
    protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
6
        long currentUserId = getFromCookie(req);
7
        User currentUser = userService.getUser(currentUserId);
8
        Book book = bookService.getBook(req.getParameter("bookId"));
9
        cartService.addToCart(currentUser, book);
10
        ...
11
    }
12
}

通过上述代码我们可以看出无论是BookService还是UserService，都通过new一个实例来创建HikariCofig，这显然造成了冗余和资源的浪费，他们明明可以共享一个HikariConfig,更准确的说是由这个配置创建的datasource。但谁来负责创建这个组件，谁又来负责管理和销毁这个组件，以处理它所带来的一系列的依赖和耦合呢，如果该组件被多个组件共享，如何确保它的使用方都已经全部被销毁？测试某个组件，例如BookService，是复杂的，因为必须要在真实的数据库环境下执行。这一系列问题，都导致了这个容器出现的必然。而在spring框架中，这个容器被命名为IOC，直译为控制反转。

IOC的原理#

传统的应用程序中，控制权在程序本身，程序的控制流程完全由开发者控制，例如：

CartServlet创建了BookService，在创建BookService的过程中，又创建了DataSource组件。这种模式的缺点是，一个组件如果要使用另一个组件，必须先知道如何正确地创建它。

在IoC模式下，控制权发生了反转，即从应用程序转移到了IoC容器，所有组件不再由应用程序自己创建和配置，而是由IoC容器负责，这样，应用程序只需要直接使用已经创建好并且配置好的组件。为了能让组件在IoC容器中被“装配”出来，需要某种“注入”机制，例如，BookService自己并不会创建DataSource，而是等待外部通过setDataSource()方法来注入一个DataSource：

1
public class BookService {
2
    private DataSource dataSource;
3

4
    public void setDataSource(DataSource dataSource) {
5
        this.dataSource = dataSource;
6
    }
7
}

不直接new一个DataSource，而是注入一个DataSource，这个小小的改动虽然简单，却带来了一系列好处：

BookService不再关心如何创建DataSource，因此，不必编写读取数据库配置之类的代码；
DataSource实例被注入到BookService，同样也可以注入到UserService，因此，共享一个组件非常简单；
测试BookService更容易，因为注入的是DataSource，可以使用内存数据库，而不是真实的MySQL配置。

因此，IoC又称为依赖注入（DI：Dependency Injection），它解决了一个最主要的问题：将组件的创建+配置与组件的使用相分离，并且，由IoC容器负责管理组件的生命周期。

在ioc里容器里，所有的组件都被叫做Javabean,即配置一个组件就是配置一个Bean。这句话让我受益匪浅。

Xml配置#

在spring框架里，有自带的application.xml文件。在里面，你可以自己管理所有的bean。

1
<?xml version="1.0" encoding="UTF-8"?>
2
<beans xmlns="http://www.springframework.org/schema/beans"
3
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
    xsi:schemaLocation="http://www.springframework.org/schema/beans
5
        https://www.springframework.org/schema/beans/spring-beans.xsd">
6

7
    <bean id="userService" class="com.itranswarp.learnjava.service.UserService">
8
        <property name="mailService" ref="mailService" />
9
    </bean>
10

11
    <bean id="mailService" class="com.itranswarp.learnjava.service.MailService" />
12
</beans>

bean对象通过管理和标识，来注入别的bean对象

注解配置#

像上面的xml配置，缺点弊端一目了然，一想便知，每构造一个bean对象，我们就要在xml里配置注入ioc容器，组件和组件之间的依赖写起来也十分麻烦，容易遗忘，不便于维护。

于是

spring引出了注解。

1
@Component
2
public class MailService {
3
    ...
4
}

这个@Component注解就相当于定义了一个Bean，它有一个可选的名称，默认是mailService，即小写开头的类名。

然后，我们给UserService添加一个@Component注解和一个@Autowired注解：

1
@Component
2
public class UserService {
3
    @Autowired
4
    MailService mailService;
5

6
    ...
7
}

使用@Autowired就相当于把指定类型的Bean注入到指定的字段中。和XML配置相比，@Autowired大幅简化了注入，因为它不但可以写在set()方法上，还可以直接写在字段上，甚至可以写在构造方法中：

1
@Component
2
public class UserService {
3
    MailService mailService;
4

5
    public UserService(@Autowired MailService mailService) {
6
        this.mailService = mailService;
7
    }
8
    ...
9
}

我们一般把@Autowired写在字段上，通常使用package权限的字段，便于测试。

最后，编写一个AppConfig类启动容器：

1
@Configuration
2
@ComponentScan
3
public class AppConfig {
4
    public static void main(String[] args) {
5
        ApplicationContext context = new AnnotationConfigApplicationContext(AppConfig.class);
6
        UserService userService = context.getBean(UserService.class);
7
        User user = userService.login("bob@example.com", "password");
8
        System.out.println(user.getName());
9
    }
10
}

除了main()方法外，AppConfig标注了@Configuration，表示它是一个配置类，因为我们创建ApplicationContext时：

1
ApplicationContext context = new AnnotationConfigApplicationContext(AppConfig.class);

使用的实现类是AnnotationConfigApplicationContext，必须传入一个标注了@Configuration的类名。

此外，AppConfig还标注了@ComponentScan，它告诉容器，自动搜索当前类所在的包以及子包，把所有标注为@Component的Bean自动创建出来，并根据@Autowired进行装配。

使用Annotation配合自动扫描能大幅简化Spring的配置，我们只需要保证：

每个Bean被标注为@Component并正确使用@Autowired注入；
配置类被标注为@Configuration和@ComponentScan；
所有Bean均在指定包以及子包内。

使用@ComponentScan非常方便，但是，我们也要特别注意包的层次结构。通常来说，启动配置AppConfig位于自定义的顶层包（例如com.itranswarp.learnjava），其他Bean按类别放入子包。

上述例子为copy，本人@componentScan理解依托，就不献丑了#

参考文献： [Jdk17官方文档]: https://doc.qzxdp.cn/jdk/17/zh/api/index.html [spring官方文档]: https://spring.io/docs [廖雪峰java文档]: https://liaoxuefeng.com/books/java/spring/ioc/annotation-config/index.html

路由的理解

Wed, 28 May 2025 00:00:00 GMT

我们先通过一个清单，从宏观到微观，勾勒出我们将要探索的知识版图：

一、路由的核心思想与现实类比
- 1.1 路由的本质定义
  - 什么是路由：寻找路径的过程
  - 路由解决的核心问题：从A到B
  - 路由的三大要素：目的地、来源、路径
- 1.2 生活中的路由案例
  - 案例一：问路与导航
  - 案例二：邮政快递系统
  - 案例三：航班中转系统
- 1.3 抽象出核心概念
  - 节点（Node）与路径（Path）
  - 下一跳（Next Hop）
  - 路由表（Routing Table）
二、计算机网络中的路由
- 2.1 路由在网络分层模型中的位置
  - OSI七层模型中的网络层
  - IP地址的角色
- 2.2 静态路由 vs. 动态路由
  - 静态路由：手动配置，简单可预测
  - 动态路由：自动学习，复杂自适应
- 2.3 常见的动态路由协议
  - 内部网关协议（IGP）：RIP, OSPF
  - 外部网关协议（EGP）：BGP
三、Web应用开发中的路由
- 3.1 后端路由
  - 定义：URL到处理函数的映射
  - 案例：Express.js / Spring MVC
  - RESTful API设计理念
- 3.2 前端路由
  - 定义：在单页面应用（SPA）中管理视图切换
  - 实现模式：Hash模式 vs. History模式
  - 案例：React Router / Vue Router
- 3.3 前后端路由的协作与区别
  - 协作模式
  - 核心区别
四、路由的挑战与未来
- 4.1 路由算法的核心
  - 距离矢量算法
  - 链路状态算法
- 4.2 路由面临的挑战
  - 路由安全
  - 策略路由与QoS
  - 可扩展性
- 4.3 未来的路由技术
  - 软件定义网络（SDN）
  - 意图驱动网络（IDN）

现在，让我们开始第一部分，从最直观、最根本的层面理解路由的核心思想。

第一部分：路由的核心思想与现实类比#

开场 (SCQA + Why)#

(S) 情境 (Situation): 在我们的数字世界（发送邮件、浏览网页）和现实世界（寄快递、开车出行）中，信息和物体无时无刻不在从一个地方移动到另一个地方。
(C) 冲突 (Complication): 但它们并不知道如何从起点A自动到达遥远的终点B。一个数据包离开你的电脑时，它对全球互联网的复杂结构一无所知；一个快递包裹离开你家时，它也不知道如何穿越大半个国家到达收件人手中。
(Q) 问题 (Question): 那么，我们如何为这些信息或物体规划出一条高效、可靠的路径，引导它们一步步走向最终目的地呢？
(A) 回答 (Answer): 这就是“路由”要解决的核心问题。路由（Routing）的本质，就是为数据或物体在网络中选择路径的过程。今天，我们先不谈复杂的代码和协议，而是通过生活中熟悉的例子，来构建对路由最核心、最牢固的理解。

方案介绍 (How + 类比)#

（给地图） 为了理解路由，我们可以把它拆解成三个我们非常熟悉的现实世界案例。这三个案例就像三种不同的“案例片段”，分别揭示了路由的一个侧面。

（讲细节+用类比）

案例一：街头问路 (揭示了“下一跳”的概念)
- 场景： 你在一个陌生的城市，要去一个著名景点。你不知道完整路线，但你看到一个警察。
- 你的行为： 你问警察：“你好，请问去XX景点怎么走？”
- 警察的回答： 他不会告诉你从当前位置到景点的每一步。他会说：“哦，你沿着这条路直走，到下一个路口左转，就能看到地铁站了，坐地铁3号线就能到。”
- 核心洞察： 这个警察就是一个“路由器”。他不需要知道全程，他只需要根据你的“目的地”（景点），为你指出**“下一跳” (Next Hop)**——也就是你下一步应该去的地方（路口左转的地铁站）。你到达下一跳后，再寻找新的指引。互联网上的路由器就是这样工作的，它们接力式地把数据包一跳一跳地传向目的地。
案例二：邮政快递系统 (揭示了“分层”与“地址”的概念)
- 场景： 你从北京寄一个快递到深圳南山区的一个具体地址。
- 过程：
  - 你把包裹交给家门口的快递员。他不需要知道去深圳的具体路线，他只需要把包裹送到本地分拣中心。
  - 本地分拣中心看到“深圳市”，就把包裹发往北京的区域枢纽。
  - 北京枢纽将所有发往华南的包裹集中起来，通过飞机或高铁发往深圳的区域枢纽。
  - 深圳枢纽看到“南山区”，就把它发往南山区的分拣中心。
  - 最终，南山的快递员才看到完整的街道门牌号，并送到收件人手中。
- 核心洞察： 这是一个典型的分层路由系统。每一层的“路由器”（快递员、分拣中心、枢纽）只关心自己这一层级的任务。这个系统依赖一个结构化的“地址”（国家-省-市-区-街道-门牌）来工作。IP地址的设计也遵循了类似的网络号和主机号的层级结构。
案例三：高速公路导航 (揭示了“动态”与“度量”的概念)
- 场景： 你开车从A市到B市，打开了地图App。
- App的行为： 导航App会给你几条路线选择：
  - 路线1：距离最短，但可能经过市区，红绿灯多。
  - 路线2：时间最快，全程高速，但路程更长，费用更高。
  - 路线3：躲避拥堵，这是App根据实时路况动态计算出来的。
- 核心洞察： 这里的“最佳路径”不是唯一的，它取决于你的度量标准（Metric）——是时间、距离还是费用？而且，这个最佳路径是动态变化的。如果前方发生事故，导航会立刻为你重新规划路线。在计算机网络中，动态路由协议就像一个高级的导航系统，会根据网络拥堵、链路故障等情况，动态地调整数据包的传输路径。

成果展示 (What + 可视化)#

通过这三个类比，我们可以总结出路由的核心工作逻辑。它不断地在问三个问题：

我在哪？ (数据包当前所在的路由器)
我要去哪？ (数据包的目的地地址)
怎么走最高效？ (根据路由表或算法，计算出下一跳)

我们可以用一个简单的流程图来可视化这个过程：

路由工作流程图

⭐知识点：下一跳 (Next Hop)
这是路由中最重要的核心概念之一。没有任何一个路由器需要知道到达目的地的完整路径。它只需要知道，为了到达那个最终目的地，下一步应该把这个数据包交给谁。这个“谁”就是下一跳。正是这种“只管下一步”的接力机制，使得像互联网这样庞大复杂的网络能够高效运转。

Pasule Blog

微服务架构设计原理与最佳实践

微服务架构设计原理与最佳实践#

📚 目录概览#

🎯 什么是微服务架构#

核心特征#

⚖️ 微服务vs单体应用对比#

🏗️ 微服务设计原则#

1. 单一职责原则 (Single Responsibility Principle)#

2. 数据库分离原则#

3. 无状态设计#

🛠️ 技术栈选型指南#

Spring Cloud生态系统#

容器化部署#

🏪 实战案例：电商系统微服务化#

系统架构图#

服务拆分策略#

用户服务 (User Service)#

订单服务 (Order Service)#

服务间通信#

1. 同步通信 - Feign Client#

2. 异步通信 - 消息队列#

⚠️ 常见陷阱与解决方案#

1. 分布式事务问题#

2. 服务雪崩问题#

3. 配置管理复杂性#

🚀 总结与展望#

最佳实践总结#

📖 相关阅读#

CloudFlare-ImgBed 网页上传 JPG/PNG 自动转 WebP 并保存到 Telegram 教程

1. 最终效果#

2. 整体架构#

3. 源码级改造实录#

3.1 前端：只转换 JPG/PNG#

3.2 前端：把 WebP 质量从 92% 调整为 85%#

3.3 前端：强制初始化 WebP 开关#

3.4 前端：阻止 WebP 二次压缩#

3.5 前端：WebP 关闭 Telegram 服务端压缩#

3.6 实际落地：部署前修改编译 bundle#

3.7 增加 npm 命令#

3.8 修改 GitHub Actions 顺序#

3.9 后端：删除 WebP 改名为 JPEG 的逻辑#

3.10 后端：WebP 改用 sendDocument#

3.11 Telegram API：关闭内容类型自动识别#

3.12 Telegram API：返回真实错误#

3.13 Worker 静态资源：启用 Worker-first#

3.14 Worker 静态资源：HTML 不缓存#

3.15 Cloudflare 控制台：删除旧 Workers Route#

3.16 对应的回归测试#

3.17 增删改文件汇总#

4. 前端 WebP 转换策略#

4.1 为什么必须跳过二次客户端压缩#

5. Telegram 保存策略#

5.1 使用 sendDocument#

5.2 保留文件名和 MIME#

5.3 Telegram 错误透传#

6. GitHub Actions 部署流程#

6.1 必需的 GitHub Secrets#

6.2 手动部署#

7. Cloudflare 自定义域名配置#

7.1 删除旧 CNAME#

7.2 必须检查旧 Workers Route#

8. Worker Static Assets 缓存处理#

9. 本地测试#

10. 上线验证#

10.1 先验证 workers.dev#

10.2 再验证自定义域名#

10.3 验证上传请求#

10.4 验证最终文件#

11. 常见问题#

Q1：为什么上传解析变慢，但文件还是 PNG？#

Q2：为什么请求一直是 serverCompress=true？#

Q3：为什么 cf-cache-status 仍显示 HIT？#

Q4：为什么 Telegram 上传失败后所有备用渠道也报错？#

Q5：PicGo 或 API 上传也会自动转 WebP 吗？#

Q6：上游前端更新后怎么办？#

12. 推荐的日常维护流程#

Linux 家庭服务器服务编排实战

Linux 家庭服务器服务编排实战#

第一步：目录结构要先定#

Q2：为什么请求一直是 `serverCompress=true`？#

Q3：为什么 `cf-cache-status` 仍显示 HIT？#