Skip to main content

项目包结构

🧭 短链接系统架构白皮书

本系统采用分层解耦 + 微服务聚合 + 高并发核心架构设计，兼顾开发效率与生产性能。

admin 与 project 分离保障职责单一，aggregation 聚合降低部署成本，gateway 统一治理流量，mq 异步削峰保障核心链路 SLA。

适用于亿级短链生成、百万级 QPS 跳转场景，支持企业级权限、监控、扩展。

模块说明​

cd ~/shortlink
.
├── LICENSE                             # 开源许可证文件（如 MIT、Apache 2.0 等）
├── README.md                           # 项目说明文档，包含搭建、运行、贡献指南等
├── admin                               # 后台管理服务 —— 用户管理、短链管理、分组管理、权限控制等
├── aggregation                         # 聚合服务模块 —— 将 admin 与 project 合并打包，节省部署资源，提升运维效率
├── console-vue                         # 前端控制台（Vue 项目）—— 供管理员或用户操作短链的可视化界面
├── format                              # 代码格式化配置目录
│   ├── license-header                  # 代码文件头部统一许可证/版权注释模板
│   └── short-link_spotless_formatter.xml  # Spotless 格式化规则文件，统一 Java 代码风格
├── gateway                             # API 网关服务 —— 路由分发、鉴权、限流、日志等统一入口（如 Spring Cloud Gateway）
├── lombok.config                       # Lombok 全局配置文件，控制 @Data、@Log 等注解行为
├── mvnw                                # Maven Wrapper（Unix/Linux/Mac）—— 无需预装 Maven，统一构建环境
├── mvnw.cmd                            # Maven Wrapper（Windows）—— Windows 下的 Maven 构建脚本
├── pom.xml                             # Maven 项目主配置文件 —— 管理依赖、插件、模块聚合等
├── project                             # 核心短链服务 —— 生成、跳转、统计、缓存等核心业务逻辑
└── resources                           # 项目公共资源目录
    └── database                        # 数据库脚本 —— 建表语句、初始化数据、迁移脚本等
架构设计亮点💡
  • 轻量聚合：通过 aggregation 模块实现“开发期分离，部署期合并”，兼顾微服务灵活性与单体部署成本。
  • 前后端分离：console-vue 独立前端工程，支持独立迭代、热更新、权限动态控制。
  • 标准化工程：Spotless + Lombok + Maven Wrapper 保障团队代码风格、构建环境统一，降低协作成本。

目录说明​

1. 后管系统​

📌 定位：面向运营/管理员的配置型系统，强调数据一致性、权限精细控制、操作可追溯。

技术特点：用户权限模型、Excel 批量导入导出（多线程）、分页查询优化、远程调用熔断降级。

cd ~/com.nageoffer.shortlink.admin

.
├── ShortLinkAdminApplication.java      # Spring Boot 启动类 —— 项目入口，配置组件扫描与启动参数
├── common                              # 通用模块 —— 被多个模块复用的基础组件、工具、常量等
│   ├── biz                             # 业务通用组件 —— 如用户上下文、用户操作流量风控过滤器等
│   ├── constant                        # 全局常量类 —— 错误码、业务状态、系统配置键等
│   ├── convention                      # 架构规约层 —— 统一响应结构、异常体系、分页模型等
│   ├── database                        # 数据库通用组件 —— 数据库持久层对象基础属性等
│   ├── enums                           # 枚举类 —— 业务状态枚举、类型枚举、错误码枚举等
│   ├── serialize                       # 序列化配置 —— 手机号脱敏反序列化等
│   └── web                             # Web 通用组件 —— 全局异常处理器等
├── config                              # 配置类目录 —— Spring @Configuration、Bean 定义、第三方集成配置等
├── controller                          # 控制器层 —— 接收 HTTP 请求，参数校验，调用 Service，返回响应
├── dao                                 # 数据访问层 —— 与数据库交互的接口与实体定义
│   ├── entity                          # 实体类（DO）—— 与数据库表结构一一映射
│   └── mapper                          # MyBatis / MyBatis-Plus Mapper 接口 —— SQL 操作定义
├── dto                                 # 数据传输对象 —— 用于各层之间数据传递，避免直接暴露 Entity
│   ├── req                             # 请求 DTO —— Controller 接收前端参数的封装对象
│   └── resp                            # 响应 DTO —— 返回给前端的数据结构，可包含业务状态与数据
├── remote                              # 远程调用模块 —— 调用其他微服务（如 project、gateway）的客户端定义
│   └── dto                             # 远程调用专用 DTO —— 与其他服务约定的数据结构
├── service                             # 业务逻辑层 —— 核心业务实现，调用 DAO、远程服务、组装响应
└── toolkit                             # 工具包 —— EasyExcel、分组 ID 等工具类

2. 核心系统​

📌 定位：面向 C 端用户的高并发核心服务，强调性能、可用性、最终一致性。

技术亮点：布隆过滤器防无效请求、Base62 短码算法、RocketMQ 异步削峰、Redis 缓存、跳转 302 优化用户指标监控。

cd ~/com.nageoffer.shortlink.project

.
├── ShortLinkApplication.java           # Spring Boot 启动类 —— 核心短链服务入口，配置组件扫描与初始化
├── common                              # 通用模块 —— 被本模块复用的基础组件、常量、工具等
│   ├── biz                             # 业务通用组件 —— 如用户上下文、用户信息传输拦截器等
│   ├── constant                        # 全局常量 —— 短链前缀、默认域名、缓存 Key、业务状态码等
│   ├── convention                      # 架构规约层 —— 统一响应结构、异常体系、分页模型等
│   ├── database                        # 数据库通用组件 —— 数据库持久层对象基础属性等
│   ├── enums                           # 枚举定义 —— 跳转类型、状态、设备类型、统计维度等
│   └── web                             # Web 通用组件 —— 全局异常处理器等
├── config                              # 配置类 —— 注册 Bean、第三方 SDK 配置（如 Redis、RocketMQ、布隆过滤器等）
├── controller                          # 控制器层 —— 处理短链创建、跳转、查询等 HTTP 请求
├── dao                                 # 数据访问层 —— 与数据库交互的接口与实体定义
│   ├── entity                          # 实体类（DO）—— 短链主表、访问记录表、分组表等
│   └── mapper                          # MyBatis Mapper 接口 —— 定义 SQL 操作，支持动态 SQL 与缓存
├── dto                                 # 数据传输对象 —— 各层间数据传递，避免直接暴露 Entity
│   ├── biz                             # 业务内部 DTO —— 用于 Service 层间传递复杂结构或聚合数据
│   ├── req                             # 请求 DTO —— 接收前端或网关传入的参数（如创建短链、分页查询）
│   └── resp                            # 响应 DTO —— 返回给调用方的数据结构（含跳转 URL、统计信息等）
├── handler                             # 业务处理器 —— 自定义流控策略
├── initialize                          # 初始化模块 —— 初始化短链接监控消息队列消费者组
├── mq                                  # 消息队列模块 —— 异步处理访问统计
│   ├── consumer                        # 消费者 —— 消费访问记录、更新 PV/UV等
│   ├── idempotent                      # 幂等组件 —— 基于 Redis 或数据库的幂等控制，防止重复消费
│   └── producer                        # 生产者 —— 发送短链访问事件、统计消息、异步任务等
├── service                             # 业务逻辑层 —— 短链生成、跳转逻辑、访问统计、防刷控制、缓存管理等
└── toolkit                             # 工具包 —— 短链算法（Base62、Hash）等
🚀 性能保障设计
  • 跳转链路 < 5ms：通过 Redis + 布隆过滤器 + 缓存空值 + 分布式锁四级拦截无效请求。
  • 生成链路 < 50ms：Snowflake 分布式 ID + Base62 编码 + 布隆过滤器 + 缓存预热。
  • 统计链路最终一致：访问事件异步入库，不影响主路径性能。

Table of Contents