# Part 4: 技术架构设计

> **文档定位**：深入剖析系统关键技术组件的选型策略、实现原理及落地实践，为解决高并发、分布式一致性等复杂工程问题提供标准方案。

## 4.1 服务治理体系 (Service Governance)

基于 **Alibaba Nacos 2.x** 构建统一的注册中心与配置中心，解决微服务架构下的服务发现与配置管理难题。

### 4.1.1 动态配置管理
*   **设计原则**：配置即代码，环境隔离。
*   **命名空间 (Namespace)**：严格按照环境划分（Dev/Test/Prod），确保环境间配置物理隔离。
*   **配置共享**：
    *   **通用配置**：`application-common.yaml`（Redis、MyBatis Plus、Swagger 等基础中间件配置）。
    *   **应用配置**：`viewsh-module-{app}-{profile}.yaml`（业务专属配置）。
*   **热更新机制**：基于 Spring Cloud `@RefreshScope` 注解，实现日志级别调整、限流阈值变更等场景的**零停机动态刷新**。

### 4.1.2 服务注册与发现
*   **领域模型隔离**：微服务实例启动时自动注册至 Nacos，通过 `Group` 区分子略（如 `DEFAULT_GROUP`），支持基于元数据（Metadata）的版本灰度路由。
*   **健康检查**：开启 Nacos 临时实例模式（Ephemeral=true），基于心跳机制（5s/次）自动剔除亚健康实例。

---

## 4.2 异步消息体系 (Messaging Architecture)

采用 **Apache RocketMQ 5.x** 作为核心消息总线，承担**削峰填谷**与**领域解耦**重任。

### 4.2.1 Topic 规划设计
遵循“业务域.类型.动作”的命名规范：
*   **IoT 遥测数据**：`IOT_DEVICE_UP` (Tag: `Telemetry`, `Event`)
    *   *特征*：高吞吐，允许少量丢失，使用普通消息。
*   **业务状态变更**：`OPS_WORK_ORDER` (Tag: `Create`, `Complete`)
    *   *特征*：低延迟，强一致性，使用事务消息或同步重试机制。

### 4.2.2 可靠性保证
1.  **生产端**：开启同步发送模式（Sync Send），配置重试次数 `retryTimesWhenSendFailed=2`。
    
    ```java
    // 消息发送示例
    @Resource
    private RocketMQTemplate rocketMQTemplate;

    public void sendDeviceEvent(DeviceEvent event) {
        // 构建消息
        Message<DeviceEvent> message = MessageBuilder.withPayload(event)
            .setHeader(RocketMQHeaders.KEYS, event.getEventId()) // 设置 Key 方便检索
            .build();
        
        // 同步发送，等待结果
        SendResult result = rocketMQTemplate.syncSend("IOT_DEVICE_UP:Telemetry", message);
        log.info("Send result: {}", result.getSendStatus());
    }
    ```

2.  **消费端**：
    *   **幂等处理**：在消费者业务逻辑中必须校验 `BizKey`（如工单号、消息ID）是否已处理。
    *   **死信队列 (DLQ)**：消费失败重试 16 次后自动进入 DLQ，需人工介入排查。

---

## 4.3 高并发防护 (System Resilience)

引入 **Sentinel** 实现全方位的流量控制与熔断降级。

### 4.3.1 网关层防护
*   **流量清洗**：针对 API Gateway 设置集群限流规则（Cluster Flow Control），限制单 IP 或单用户的 QPS，防止恶意刷接口。
*   **热点参数限流**：针对 SKU ID、Device ID 等热点参数配置特例化限流规则。

### 4.3.2 服务层熔断
*   **微服务调用**：Feign Client 集成 Sentinel 熔断器，当调用错误率超过 50% 或响应时间 > 1s 时自动熔断，快速失败，防止雪崩效应。
    
    **配置示例 (bootstrap.yaml)**：
    ```yaml
    feign:
      sentinel:
        enabled: true # 开启 Feign Sentinel 支持
    
    spring:
      cloud:
        sentinel:
          transport:
            dashboard: localhost:8080 # Sentinel 控制台地址
          scg:
            fallback:
              mode: response
              response-body: '{"code": 429, "msg": "服务繁忙，请稍后重试"}'
    ```

*   **降级策略**：核心业务（如登录）必须配置 `fallback` 降级逻辑，返回友好的兜底数据。

---

## 4.4 分布式锁与幂等性 (Distributed Lock & Idempotency)

针对分布式环境下的并发竞争问题，提供标准化的解决方案组件。

### 4.4.1 分布式锁 (`Lock4j`)
集成 `Lock4j` 框架，基于 **Redis (Redisson)** 实现。

**使用示例**：
```java
@Service
public class OrderService {

    @Autowired
    private OrderMapper orderMapper;

    // 锁住 orderId，防止并发修改
    // expire: 锁过期时间 60s
    // acquireTimeout: 获取锁超时时间 1s
    @Lock4j(keys = {"#orderId"}, expire = 60000, acquireTimeout = 1000)
    public void updateOrderStatus(Long orderId, String status) {
        OrderDO order = orderMapper.selectById(orderId);
        if (order == null) {
             throw new BusinessException("订单不存在");
        }
        order.setStatus(status);
        orderMapper.updateById(order);
    }
}
```

*   **看门狗机制**：对于长耗时业务，Redisson Watchdog 自动续期锁过期时间，防止业务未执行完锁被释放。
*   **应用场景**：定时任务防重、库存扣减、设备指令下发。

### 4.4.2 幂等性组件 (`@Idempotent`)
自研幂等性切面 `com.viewsh.framework.idempotent`。
*   **实现原理**：
    1.  **Key 生成**：支持多种策略，包括 HTTP Header 值、SpEL 表达式、请求参数 MD5。
    2.  **原子操作**：利用 Redis `setNX` 指令占位，设置较短的过期时间（默认 1s）。
    3.  **异常处理**：重复请求直接抛出 `IdempotentException`，全局异常处理器统一拦截返回 `429 Too Many Requests`。
*   **应用场景**：表单重复提交、支付回调接口。

---

## 4.5 数据一致性设计 (Data Consistency)

### 4.5.1 最终一致性 (Saga/MQ)
绝大多数业务场景采用基于 MQ 的最终一致性方案。
*   **本地事务表**：核心业务（如工单）执行本地事务时，记录“待发送消息”至本地表。
*   **异步投递**：通过定时任务扫描本地表，投递至 MQ，确保消息不丢失。
*   **消费确认**：下游服务消费成功后，回调更新状态。

### 4.5.2 强一致性 (Seata)
对于资金转账等极其敏感的跨库场景，预留 **Seata AT** 模式支持。
*   *注*：当前核心业务流（IoT设备上报、Ops工单流转）设计上规避了强一致性需求，优先保障高可用与吞吐量。