--- title: "00-各模块吃透" created: 2025-12-08 aliases: - 各模块吃透 tags: - 项目 --- # 各模块吃透 ## 项目结构 ![[image-5ff2da75.png]] ```text damai_pro/ ├── damai-captcha-manage-framework # 验证码组件模块 │ ├── damai-base-captcha # ├── 验证码基础组件 (底层逻辑实现) │ └── damai-captcha-framework # └── 验证码封装组件 (对外提供服务) │ ├── damai-common # 公共基础包 (通用工具类、常量、异常定义等) │ ├── damai-elasticsearch-framework # Elasticsearch封装组件 (搜索服务集成) │ ├── damai-id-generator-framework # 分布式ID生成器 (百度UidGenerator/雪花算法) │ ├── damai-redis-tool-framework # Redis相关组件 │ ├── damai-redis-common-framework # ├── Redis公共配置模块 │ ├── damai-redis-framework # ├── Redis操作封装组件 (缓存操作) │ └── damai-redis-stream-framework # └── RedisStream操作封装组件 (消息队列) │ ├── damai-redisson-framework # Redisson封装组件 │ ├── damai-redisson-service-framework # ├── Redisson服务相关组件 │ │ ├── damai-bloom-filter-framework # │ ├── 布隆过滤器组件 (防缓存穿透) │ │ ├── damai-redisson-common-framework # │ ├── 公共包 │ │ ├── damai-repeat-execute-limit-framework # │ ├── 防重复幂等组件 (接口防刷) │ │ └── damai-service-lock-framework # │ └── 分布式锁组件 (并发控制) │ └── damai-service-delay-queue-framework # └── 延迟队列组件 (基于Redis实现) │ ├── damai-server # 业务服务聚合 (后端微服务核心) │ ├── damai-admin-service # ├── Admin服务监控 │ ├── damai-base-data-service # ├── 基础数据服务 (字典、地区等) │ ├── damai-customize-service # ├── 定制化服务 (规则、策略配置) │ ├── damai-gateway-service # ├── Gateway网关服务 (路由、限流、鉴权) │ ├── damai-migrate-service # ├── 数据迁移/分库分表扩容工具 (原目录存在，补充说明) │ ├── damai-mybatis-plus-service # ├── MybatisPlus生成器 (代码生成) │ ├── damai-order-service # ├── 订单服务 (下单、订单管理) │ ├── damai-pay-service # ├── 支付服务 (对接支付宝/微信) │ ├── damai-program-service # ├── 节目服务 (商品详情、类目) │ └── damai-user-service # └── 用户服务 (登录、注册、用户中心) │ # 注：原描述中提到的 damai-single-service 在此文件树中未包含，以 damai-migrate-service 替代 │ ├── damai-server-client # 业务服务的Feign Client (服务间调用SDK) │ ├── damai-base-data-client # ├── 基础数据服务-Feign调用 │ ├── damai-customize-client # ├── 定制化服务-Feign调用 │ ├── damai-job-client # ├── XXL-Job任务-Feign调用 │ ├── damai-order-client # ├── 订单服务-Feign调用 │ ├── damai-pay-client # ├── 支付服务-Feign调用 │ ├── damai-program-client # ├── 节目服务-Feign调用 │ └── damai-user-client # └── 用户服务-Feign调用 │ ├── damai-spring-cloud-framework # 微服务基础设施封装组件 │ ├── damai-service-common # ├── 服务公共包 (MybatisPlus配置、Swagger等) │ ├── damai-service-component # ├── 微服务公共包 (Feign拦截器、过滤器等) │ ├── damai-service-gray-transition-framework # ├── 灰度功能组件 (负载均衡、灰度发布) │ └── damai-service-initialize # └── 服务初始化行为管理组件 (启动加载逻辑) │ ├── damai-thread-pool-framework # 线程池封装组件 (统一管理线程资源) │ ├── spotless # 代码格式化工具配置 │ ├── sql # 数据库脚本 │ ├── cloud # ├── 基础建库建表脚本 │ ├── 将虚拟分片路由映射表重置为2库4表分片 # ├── 分库分表初始化脚本 │ └── 虚拟分片路由下进行分库分表扩容 # └── 扩容脚本 │ ├── vue3 # 前端项目源码 (基于Vue3 + Vite) │ ├── LICENSE ├── pom.xml # 父工程Maven配置文件 └── README.md # 项目说明文档 ``` ## 1. 核心背景：为什么需要组件化？ 在从单体架构向分布式/微服务架构演进的过程中，我们面临的核心痛点是**“规模化带来的重复与失控”**。 - **痛点**：微服务架构下，服务数量动辄成百上千。如果每个服务都需要写一遍“分布式锁”、“缓存逻辑”或“线程池配置”，代码将极度冗余，且一旦需要升级（例如Redis升级），涉及修改的服务太多，维护成本极高 。 - **解决方案**：将通用逻辑抽取出来，封装成独立的**组件库 (Project)**。 - **落地方式**：其他业务服务通过 **Maven 依赖** 引入这些组件，实现“写一次，处处调用”，提高代码复用性和开发效率 。 ## 2. 演进路径：从 Util 到 Starter 组件的设计不仅仅是封装工具类，而是结合 Spring Boot 特性进行架构升级，特别是针对不同版本的兼容性设计。 - **1.0 时代 (Spring Util)**：简单的 Maven 依赖。开发者引入 jar 包后，可能还需要手动配置 XML 或 Bean，复用性有余但易用性不足 。 - **2.0 时代 (Spring Boot Starter)**：**高级组件形态**。 - **核心机制**：利用 Spring Boot 的**自动装配 (Auto-Configuration)** 机制。 - **优势**：约定大于配置。引入依赖后，组件自动根据环境加载配置，开发者只需极少的配置即可获得完整功能 。 - **架构深水区：Spring Boot 2 vs 3 的断代差异** - **挑战**：Spring Boot 3.0 (JDK 17+) 对自动装配机制进行了重大变更，废弃了 `spring.factories`。 - **差异**： - **SB 2.x**：依赖 `META-INF/spring.factories` 注册配置类。 - **SB 3.x**：依赖 `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` 文件。 - **大麦落地**：为了同时支持新老项目，组件设计采用了 **Base (核心逻辑) + Framework (装配层)** 的分离结构，针对不同版本编写不同的装配模块 。 ## 3. 大麦项目组件版图 (架构落地) 大麦项目的组件设计覆盖了基础设施、中间件增强、服务治理等多个维度，充分体现了**高内聚、低耦合**的设计思想。 ### 3.1 基础设施增强类 这类组件解决的是“基础技术栈在生产环境不够好用”或“容易误用”的问题。 - **Redis 增强** (`damai-redis-tool-framework`)： - **痛点**：原生 `RedisTemplate` 操作繁琐，且 Key 接收 String 类型，容易导致 Key 命名混乱、无法管理 。 - **方案**：统一 Key 的前缀管理，封装对象序列化/反序列化逻辑，强制规范化使用 。 - **扩展**：封装 Redis Stream 实现轻量级消息队列 。 - **Elasticsearch 增强** (`damai-elasticsearch-framework`)： - **方案**：针对 ES 的索引创建、数据查询/添加进行定制化封装，简化复杂的查询 API 调用 。 - **线程池管理** (`damai-thread-pool-framework`)： - **痛点**：在微服务链路追踪（SkyWalking）或日志 MDC 场景下，**主线程的上下文数据（如 TraceID）无法自动传递到子线程中**，导致链路断裂 。 - **方案**：采用装饰者模式增强线程池，在任务提交时自动捕获并传递上下文（ThreadLocal），执行完毕后清理，防止内存泄漏 。 ### 3.2 高并发与稳定性保障类 这是大麦作为票务系统的核心竞争力组件，解决“抢票”场景下的并发问题。 - **分布式锁** (`damai-service-lock-framework` / `damai-redisson-framework`)： - **实现**：基于 Redisson 封装。不仅仅是 `lock()`，还包括锁的粒度控制、看门狗机制（自动续期）、公平锁/读写锁的配置 。 - **延迟队列** (`damai-service-delay-queue-framework`)： - **场景**：用户下单后 15 分钟未支付自动取消订单。 - **技术**：基于 Redis ZSet 或 Redisson `RDelayedQueue` 实现高性能延迟消息，替代传统的轮询数据库方案 。 - **限流与防刷** (`damai-repeat-execute-limit-framework`)： - **功能**：提供接口幂等性校验（防止前端重复提交或网络重试导致的数据重复处理）以及恶意请求拦截 。 - **熔断降级**： - 集成 Hystrix（经典方案）和 Sentinel（新一代方案），用于服务雪崩保护 。 ### 3.3 分布式服务治理类 解决微服务之间协作、数据一致性和环境隔离的问题。 - **分布式 ID** (`damai-id-generator-framework`)： - **痛点**：传统的雪花算法依赖机器 ID (WorkerId)。在 **K8s 容器化环境**下，容器重启会导致 IP 变化，容易引发 WorkerId 重复，从而导致主键冲突 。 - **方案**：优化雪花算法，利用 Redis 或 Zookeeper 动态分配和回收 WorkerId，确保 ID 全局唯一 。 - **分库分表** (`damai-spring-cloud-framework` 下的 `service-common`)： - **方案**：集成 ShardingSphere，采用**基因法**分片策略，解决“既要按用户 ID 查订单，又要按商家 ID 查订单”的多维查询难题 。 - **灰度发布与环境隔离** (`damai-spring-cloud-framework` 下的 gray 模块)： - **方案**：实现全链路灰度。通过在网关层打标，并在下游服务透传标记，让测试流量只打到灰度机器，保证生产/灰度环境的数据和流量严格隔离 。 - **注册中心切换**： - 支持在 Nacos 等不同注册中心之间灵活切换，防止被单一组件绑定 。 ### 3.4 业务通用类 - **验证码组件** (`damai-captcha-manage-framework`)： - 封装统一的图形验证码逻辑，屏蔽底层的生成细节，业务层直接调用校验接口 。 - **服务初始化** (`damai-service-initialize`)： - **痛点**：服务启动时通常需要预热缓存或加载配置，代码散落在各个 `CommandLineRunner` 中，难以管理顺序。 - **方案**：统一管理各个微服务启动时的初始化行为，定义标准接口和执行顺序 。 ## 4. 学习核心：组件设计的思考维度 通过这个项目，不应只学习如何“使用”组件，更要学习如何“设计”一个标准组件 。在设计组件时，架构师通常考虑以下因素： 1. **通用性**：剥离具体业务逻辑（如具体的订单状态），只保留通用技术逻辑（如“延迟执行”的能力）。 2. **扩展性**：利用设计模式（如模板方法、策略模式），允许业务方在使用时进行定制（例如自定义锁的 key 生成规则）。 3. **易用性**：利用 Starter 机制，做到“引入即用”，通过 `application.yml` 暴露必要的配置项，屏蔽底层复杂性。 4. **复用性**：通过 Maven 仓库分发，版本化管理，提升团队整体开发效率 。 --- **总结**： 微服务架构的本质不仅是服务的拆分，更是**公共能力的下沉**。大麦项目通过构建一套完善的 `Framework` 层，让上层的 `Server` (业务服务) 只需要关注具体的购票逻辑，而将复杂的并发控制、资源管理、分布式治理交由底层组件处理。这是从“写代码”进阶到“做架构”的必经之路。 --- **企业级项目导航**：⬅️ [[08-项目的接口文档|08-项目的接口文档]] | 00-各模块吃透 | ➡️ [[00-数据库表关系|00-数据库表关系]]