系统设计——项目设计经验总结3
摘要
本文主要分享了 Java 开发中的项目设计经验总结，包括 common 包的内容分类及最佳实践建议、RPC 接口的放置位置、引用关系数据模型设计、阿里软件上线发布流程规范和最佳实践以及分布式系统流量东西/南北控制设计等内容，旨在为 Java 开发人员提供项目设计方面的参考和指导。
1. 项目comm jar包内容应该放里面？
一个项目的 common 包（或称为 comm 包、common 模块、基础工具包）是整个系统的 基础能力集合，用于存放 无业务逻辑、通用、可复用、稳定 的组件或工具，适用于多个业务模块之间共享使用。通常应该放在 common 包的内容分类如下：
1.1. ✅ 通常应该放在 common 包的内容分类如下：
1.1.1. 1️⃣ 工具类（Utils）
| 工具类名称 | 功能说明 |
|
| 日期时间格式化、时间差计算等 |
|
| 封装 Jackson / Fastjson 操作 |
|
| 字符串处理封装（如果不依赖 Apache Commons） |
|
| Bean 拷贝（如使用 Spring BeanUtils MapStruct） |
|
| 封装雪花算法、UUID、IDWorker 等唯一 ID 生成器 |
|
| 文件读写、上传封装 |
1.1.2. 2️⃣ 通用常量（Constants）
| 类名 | 内容 |
|
| 项目级别的通用常量，如系统编码、token 前缀等 |
|
| Redis key 统一前缀 |
|
| HTTP 状态码枚举封装 |
|
| 通用错误码定义 |
1.1.3. 3️⃣ 自定义注解 + AOP（横切逻辑）
| 类型 | 用途 |
|
| 分布式锁注解 |
|
| 统一日志记录 |
|
| 数据权限注解 |
|
| 对应的切面逻辑（如日志切面、分布式锁切面） |
1.1.4. 4️⃣ 通用异常体系
| 内容 | 描述 |
|
| 业务基础异常类，继承 |
|
| 带错误码/错误消息的业务异常 |
|
| 统一错误枚举 |
|
| 全局异常处理器(用于Spring |
1.1.5. 5️⃣ 通用响应封装类（统一返回结构）
| 类名 | 功能 |
|
| 通用响应结构：封装 |
|
| 带分页的返回结构 |
|
| 标准响应码枚举（如 SUCCESS、FAIL、ILLEGAL_PARAM 等） |
1.1.6. 6️⃣ 枚举（Enums）
- 性别、状态、布尔值（YES/NO）、平台类型、支付渠道等通用枚举
- 可以统一实现
BaseEnum接口，便于映射 code → enum
1.1.7. 7️⃣ 基础接口或抽象类
| 类型 | 功能 |
|
| 公共实体字段（如 |
|
| 公共 controller 操作（如获取当前用户） |
|
| 通用错误码接口 |
|
| 通用 MyBatis Mapper 接口（可选） |
1.1.8. 8️⃣ 通用配置类（Config）
| 配置 | 功能 |
|
| 自定义序列化规则 |
|
| 跨域配置 |
|
| Feign 全局设置 |
|
| 自定义线程池配置 |
1.1.9. 9️⃣ 网络 & 中间件封装
| 类型 | 说明 |
| Redis 封装 |
|
| MQ 工具类 | Kafka / RocketMQ 封装工具 |
| Web 工具 | IP 工具、请求参数解析等 |
1.2. ✅ 推荐包结构示例：
common
├── annotation // 注解
├── aspect // AOP 切面
├── config // 通用配置类
├── constant // 常量类
├── enums // 枚举类
├── exception // 异常处理
├── model // 通用实体，如 Result、PageResult
├── util // 工具类
├── lock // 分布式锁（注解 + 实现）
└── ...1.3. ✅ 最佳实践建议
- 不放任何业务逻辑（如订单、用户、积分等业务域代码）
- 尽量通用稳定，一旦发布不要轻易变动
- 建议设置成单独Maven模块，独立打包
common.jar供其他模块依赖
2. RPC接口应该放在哪一层？
例如放在 common-utils、common-base 中，这是错误的，因为这些模块主要是放工具类、基础类（如枚举、通用响应体等），而 RPC 接口具有明确业务依赖，不应该混进工具模块中。
2.1. ✅ 建议：在 Service 层单独建立 client 或 remote 包
📦 项目结构示例：
order-service/└── src/main/java/com/xxx/order/service/├── client/RemoteUserClient.java （仅订单服务内部使用）└── OrderService.java2.2. ✅ 优势：
- 结构清晰、简单。
- 避免过度模块化，减少项目依赖。
3. 引用关系数据模型设计
4. 阿里软件上线发布流程规范和最佳实践
4.1. 第一板斧：预发布（灰度发布）
核心目标：确保新版本在小流量下运行无异常
- 灰度环境验证：将新版本先发布到部分服务器或少量用户进行验证。
- 自动化测试和回归测试：确保代码变更没有引入新的问题。
- 监控预设：设置业务、系统、接口等多维度监控项。
- 验证指标：
-
- 接口响应时间是否异常
- 错误率是否上升
- 关键链路是否完整
4.2. 第二板斧：正式发布（全量发布）
核心目标：平滑、稳定、安全地将新版本推向生产环境
- 发布策略
-
- 滚动发布：一台一台机器发布
- 弹性伸缩：先扩容新版本，再逐步缩容旧版本
- 发布窗口控制：避开业务高峰期，一般选择业务低峰时段。
- 观察期控制：每一小步发布后都会设定观察时间，确认无异常再继续。
- 应急预案准备：出现问题可立即启用“回滚”机制。
4.3. 第三板斧：发布后验证和回滚机制
核心目标：发布后及时发现并解决问题，必要时快速回滚
- 发布后验证
-
- 自动或人工检查各项指标是否正常（如QPS、RT、异常数等）
- 用户反馈监测（如客服、监控告警）
- 回滚机制
-
- 支持一键回滚到上一个稳定版本
- 回滚策略需提前演练
4.4. 为什么叫“三板斧”？
- “三板斧”在中国传统语境中，代表的是一套成熟、有力、效果显著的做事套路。
- 在阿里，“三板斧”作为文化象征，强调每个步骤都不能缺少，是确保发布“稳、准、快”的秘诀。
4.5. 上线发布流程规范总结
阿里巴巴的“发布三板斧”强调的是：
- 先小范围试水（灰度）；
- 逐步放量稳定推进（全量）；
- 实时观察、快速兜底（验证&回滚）。
这套流程在大型互联网公司中被广泛借鉴和推广，也体现了工程效率与系统稳定性的平衡哲学。
5. 分布式系统流量东西/南北控制设计？
5.1. 南北向流量（North-South Traffic）控制
🧭 定义：
- 指 客户端 ↔ 服务端 之间的流量。
- 如：用户从浏览器访问你的网站，请求进入系统，是从 外部 → 内部 的流量。
🎯 关键控制点：
- 边界网关（API Gateway）
- 负载均衡器（SLB、Nginx、Envoy）
- WAF（Web Application Firewall）
- 限流、防刷、认证、黑白名单
控制手段示例：
| 目标 | 控制方式 |
| 防止流量突刺 | 接入层限流（如 Nginx + Lua + redis 令牌桶） |
| 安全防护 | WAF 防御 SQL 注入、XSS、CSRF 等攻击 |
| 接口授权 | OAuth2 / JWT 等认证鉴权机制 |
| 访问频控 | 用户维度限流（每 IP、每用户每分钟次数） |
5.2. 东西向流量（East-West Traffic）控制
🧭 定义：
- 指 服务 ↔ 服务 之间的调用流量，横向流量。
- 如：A 服务调用 B 服务、订单系统调用库存系统。
🎯 关键控制点：
- 服务网格（Service Mesh）
- 服务治理框架（Spring Cloud、Dubbo）
- Sidecar（如 Istio 的 Envoy）
✅ 控制手段示例：
| 目标 | 控制方式 |
| 服务调用限流 | Sentinel、Resilience4j、Hystrix |
| 熔断 & 降级 | 服务之间调用失败后自动降级/超时熔断 |
| 超时控制 | 设置服务间调用最大响应时间 |
| 服务认证 | JWT + mTLS 双向认证，防止服务伪装 |
| 流量染色 | 灰度发布时标记流量走新版本 |
| 请求路由 | Istio 等网格中配置 virtualService 实现路由控制 |
5.3. 实际工程中控制方案总结
| 方向 | 场景 | 工具/技术 |
| 南北向流量控制 | 用户 → 系统入口 | Nginx、API Gateway、WAF、限流组件 |
| 东西向流量控制 | 服务 → 服务 | Sentinel、Istio、Spring Cloud Gateway、Ribbon、服务网格 |
5.4. 企业级实战建议
- 南北向：建议所有外部请求都统一走 API 网关层，统一做鉴权、限流、安全防护。
- 东西向：内部服务应接入服务注册中心（Nacos、Consul）、服务限流（Sentinel），并逐步引入 Service Mesh 实现细粒度治理。
- 可观测性：引入链路追踪系统（如 SkyWalking、Zipkin）观察流量路径和性能瓶颈。
- 故障演练：压测和故障注入平台（如 ChaosBlade）模拟流量突发，测试限流/熔断机制有效性。
博文参考
《阿里巴巴java开饭规范》