← 返回学习路线

SYSTEM

设计决策与原则

后端实战八、设计决策与原则blog-dev
src/content/notes/blog-dev/设计决策与原则.md

八、设计决策与原则

8.1 包结构约定

包 放什么 不放什么
security JWT 工具、认证过滤器 通用工具
util RedisUtil、StringUtils 业务逻辑
config RedisConfig、SecurityConfig 业务代码
common Result、PageResult、异常 服务私有代码

8.2 注入方式

统一使用构造器注入 + Lombok @RequiredArgsConstructor,不用 @Autowired 字段注入:

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    private final UserRepository userRepository;
    private final RedisUtil redisUtil;
}

8.3 Fail-fast 原则

关键组件初始化时立即校验配置,不等到运行时:

@Component
public class JwtUtil {
    public JwtUtil(@Value("${jwt.secret-key}") String secretKey, ...) {
        if (secretKey == null || secretKey.isBlank()) {
            throw new IllegalArgumentException("JWT secret-key 未配置");
        }
        this.key = Keys.hmacShaKeyFor(secretKey.getBytes(StandardCharsets.UTF_8));
    }
}

8.4 密码类配置安全

# 正确:默认 null,跳过 AUTH
password:[已隐藏]

# 错误:默认空字符串,触发无效 AUTH
password:[已隐藏]

8.5 环境变量命名规范

变量 用途 默认值
REDIS_PASSWORD Redis 密码 null(无密码)
DB_PASSWORD MySQL 密码 无默认值(必填)
JWT_SECRET_KEY JWT 签名密钥 开发默认值
NACOS_ADDR Nacos 地址 localhost:8848
CORS_ALLOW 跨域白名单 http://localhost:5173

九、遗留问题与后续规划

当前遗留(低优先级,不影响运行)

模块 问题
父 POM spring-cloud-starter-webflux 在 dependencyManagement 中用了错误 groupId
article-service pom.xml 空标签噪音(<scm>、<licenses>、<developers>)
blog-common spring-boot-starter-web 和 spring-boot-starter-data-jpa 可精简为 spring-web + spring-data-commons

Phase 3 规划

功能 说明
文章阅读量 Redis 计数器 + 定时同步 MySQL
评论缓存 Redis 缓存评论列表
评论者昵称 Feign 调用 user-service 获取
消息队列 RabbitMQ 异步通知
鉴权统一 Gateway 解析 JWT 并透传用户信息

十、核心经验总结

  1. 版本对齐是第一步:父 POM 统一锁定所有版本,子模块不写 version,避免版本碎片化
  2. BOM 优先于手动声明:spring-boot-dependencies 已管理的依赖不要重复声明 version
  3. 配置分层:公共配置 → Nacos,私有配置 → 本地 yml,各司其职
  4. IDE 警告 ≠ 真实错误:以命令行编译和启动日志为准
  5. Docker 中间件必须持久化:挂载数据卷,避免容器删除数据丢失
  6. 排错方法论:看启动日志 → 定位第一个异常 → 追溯根因(不只看表象)
  7. 密码默认值用 null 不用空字符串:避免中间件空串鉴权报错
  8. Phase 分阶段:Phase 2 只做基础 CRUD + Nacos 注册,不提前引入缓存和消息队列
  9. Gateway 依赖要干净:排除 Tomcat、JPA,避免和 WebFlux 冲突
  10. 构造器注入 > 字段注入:可测试性更好,依赖更明确