📋 DRAMA 融合短剧平台

开发规范建议书 v1.0
基于全系统源码审查 | 分析日期: 2026-07-21 | 覆盖 11 模块 · 5 端面 · 130+ Java 文件

1. 项目结构与模块规范

R1.1 模块命名

新模块统一命名 drama-{domain}-service。公共代码放在 drama-common。

drama-gateway/           ← API 网关
drama-common/            ← 公共工具、客户端、结果体、异常
drama-user-service/      ← 用户域
drama-content-service/   ← 内容域
drama-trade-service/     ← 交易域
...

R1.2 包结构

每个服务模块内部必须遵循统一包结构:

com.drama.fusion.{domain}/
├── {Domain}ServiceApplication.java
├── controller/          ← REST 接口
├── service/             ← 业务逻辑
├── entity/              ← MyBatis-Plus 实体
├── mapper/              ← Mapper 接口
├── config/              ← 配置类
└── client/              ← 外部服务调用

🚫 反模式:Controller 内直接 JDBC

ContentController 中存在 8+ 处 DriverManager.getConnection() 直连数据库,绕过连接池和 MyBatis。

// ❌ 禁止
var conn = java.sql.DriverManager.getConnection("jdbc:mysql://...", "root", "");
var ps = conn.prepareStatement("SELECT ...");

// ✅ 正确
@Autowired
private JdbcTemplate jdbc;   // 或 MyBatis Mapper

限时整改:所有 JDBC 直连代码替换为 JdbcTemplate 或 MyBatis Mapper。

🚫 反模式:裸线程创建

UserController 和 ContentController 中存在 6+ 处 new Thread(() -> {...}).start()

// ❌ 禁止
new Thread(() -> { spreeClient.createVendor(...) }).start();

// ✅ 正确
@EnableAsync + @Async("taskExecutor")

限时整改:替换为 Spring @Async + ThreadPoolTaskExecutor。

2. 代码风格与命名规范

R2.1 命名约定

类型命名规则示例
Controller{Domain}ControllerUserController, AdController
Service{Domain}ServiceCoinService, TradeService
Entity (DO)名词,与表名对应User, Drama, Episode
Mapper{Entity}MapperUserMapper, OrderMapper
DTO/VO后缀 DTO / VORiskCheckRequest, GoodsVO
Util{Feature}UtilJwtUtil, RsaCryptoUtil
配置类{Feature}ConfigMybatisPlusConfig
数据库表t_{entity_name}t_user, t_drama, t_order
Redis Key{domain}:{entity}:{id}rec:user:123:seen

R2.2 Lombok 使用

实体类统一使用 @Data @Builder @NoArgsConstructor @AllArgsConstructor。

Controller 统一使用 @RequiredArgsConstructor 构造注入(禁止 @Autowired 字段注入)。

R2.3 事务注解

涉及多表写操作的方法必须标注 @Transactional。事务边界内不允许远程 RPC 调用。

// ❌ 事务内 RPC
@Transactional
public void create() { dbInsert(); thirdPartyApi.call(); }  // RPC 失败不回滚

// ✅ 事务外异步
public void create() { dbInsert(); asyncService.syncToThirdParty(); }

R2.4 前端命名

  • Vue 组件: PascalCase(UploadBox.vue, MultiUpload.vue)
  • 页面路由: kebab-case(/cp/dramas, /contents/products)
  • CSS 变量驱动主题: 统一使用 var(--xxx)

3. API 设计规范

R3.1 统一响应体

所有接口统一返回 Result<T>:

{
  "code": 200,         // 200=成功, 4xx=客户端错误, 5xx=服务端错误
  "message": "success",
  "data": { ... }      // 实际数据
}

R3.2 RESTful 命名

操作Method路径
列表查询GET/api/content/dramas?page=1&size=20
详情GET/api/content/dramas/{id}
创建POST/api/content/dramas
更新PUT/api/content/dramas/{id}
删除DELETE/api/content/episodes/{id}
动作POST/api/content/drama/{id}/audit

R3.3 分页规范

// 请求
GET /api/xxx?page=1&size=20

// 响应
{ "list": [...], "total": 100, "page": 1, "hasMore": true }

管理系统默认 size=20,最大 100。

R3.4 Gateway 路由注册

新增服务必须在 Gateway application.yml 注册路由:

- id: {service-name}
  uri: lb://drama-{service-name}
  predicates: [Path=/api/{prefix}/**]

需免鉴权的端点加入 JwtAuthFilter.WHITE_LIST。

4. 数据库 & ORM 规范

R4.1 MyBatis-Plus 用法

所有数据库操作通过 MyBatis-Plus 或 JdbcTemplate。禁止 Controller 内 JDBC 直连。

// ✅ 查询
LambdaQueryWrapper<User> w = new LambdaQueryWrapper<>();
w.eq(User::getPhone, phone);
User user = userMapper.selectOne(w);

// ✅ 分页
Page<Drama> page = dramaMapper.selectPage(new Page<>(pn, ps), w);

R4.2 数据库迁移

所有 DDL 变更通过 Flyway 迁移脚本管理:

src/main/resources/db/migration/
  V20260613__user_extend.sql
  V20260615__account_status.sql
  V20260721__add_commission_log.sql

禁止手动执行 SQL 或在代码中 CREATE TABLE。

R4.3 幂等设计

金融类操作必须幂等:

// 广告激励
if (transLogMapper.selectCount(new LambdaQueryWrapper<>()
    .eq(AdTransLog::getTransId, transId)) > 0) {
    return Map.of("message", "重复交易,已核销");
}

// 支付回调
if ("PAID".equals(order.getStatus())) return "success";

🚫 反模式:无分布式锁的并发操作

CoinService.spend() 在高并发下存在余额超扣风险。金币/钱包操作必须在多实例场景下使用分布式锁。

// ✅ 使用 Redis 分布式锁
String lockKey = "lock:coin:" + userId;
if (redisTemplate.opsForValue().setIfAbsent(lockKey, "1", 5, TimeUnit.SECONDS)) {
    try { /* 余额操作 */ }
    finally { redisTemplate.delete(lockKey); }
}

5. 安全规范

R5.1 密钥管理

强制 所有密钥、密码、Token 禁止硬编码在源码或配置文件中。

# ❌ 禁止
wechat.app-secret: db4fee431fc000a1982f9e5b39e5a785

# ✅ 正确
wechat.app-secret: ${WECHAT_APP_SECRET}   # 环境变量 / K8s Secret / Vault

R5.2 JWT 认证

  • 算法: RS256(非对称签名),私钥仅 DRAMA 持有
  • 有效期: 建议 2小时 + Refresh Token,废弃当前 7天 无刷新方案
  • 吊销: 维护 Redis 黑名单,每 60 秒刷新
  • 透传: Gateway 校验后通过 X-User-Id 头传递,下游不再解析 Token

🚫 必修复:支付回调签名验证

PaymentService.verifySignature() 当前为 placeholder(始终返回 true),必须接入支付宝/微信官方签名验证 SDK。

R5.3 输入校验

  • 所有 Controller 入参必须做非空 / 长度 / 格式校验
  • 弹幕/评论/用户昵称等用户输入必须在入库前 XSS 过滤
  • SQL 必须参数化(MyBatis #{}),禁止拼接

R5.4 CORS 策略

开发环境允许全源,生产环境必须限制具体域名:

globalcors.cors-configurations:
  '[/**]':
    allowed-origins: "https://app.drama.com,https://admin.drama.com"

6. 测试规范

R6.1 测试金字塔

层级目标覆盖率框架
L1: 单元测试≥ 70%JUnit 5 + Mockito
L2: 集成测试≥ 50%@SpringBootTest + H2
L3: API 测试核心接口 100%MockMvc / Spring Cloud Contract
L4: E2E 测试核心用户旅程Playwright / Cypress

R6.2 必须覆盖的业务

优先级场景
P0金币充值/消费并发、广告激励幂等、支付回调幂等、风控评分全组合
P1三级审核状态机 (10→70)、CP 注册→审核→lilishop 同步、IM 对话历史、JWT 鉴权过滤器
P2商品卡片 CRUD、推荐算法准确性、弹幕推送、RSA 加解密

R6.3 测试命名

@Test @DisplayName("手机号登录 — 新用户自动创建画像和钱包")
void testLoginNewUser() { ... }

@Test @DisplayName("金币消费 — 余额不足应返回失败")
void testSpendInsufficientBalance() { ... }

7. Git 工作流 & CI/CD

R7.1 分支策略

main ──────●──●────────●──────●── 生产就绪
            │  │        │      │
release ────┼──┼────────●──────┼── 发布分支
            │  │               │
develop ────┼──●───────────────┼── 集成分支
            │                  │
feature ────●──────────────────┼── feature/user-login
                               │
hotfix ────────────────────────●── hotfix/payment-callback

R7.2 Commit 规范

强制 使用 Conventional Commits:

feat(coin): 添加签到领取金币功能
fix(payment): 修复支付回调签名验证
docs(api): 补充商品卡片接口文档
refactor(user): 移除 SpreeClient,迁移到 LilishopClient
test(trade): 添加并发支付测试
chore(deps): 升级 spring-boot 至 3.2.6

R7.3 Code Review

所有合并到 develop/main 的代码必须通过 PR review。Review 检查项:

  • 是否包含硬编码密钥/密码
  • 是否存在 Controller 内 JDBC 直连
  • 是否使用裸线程而非 @Async
  • 事务边界是否正确(不含 RPC)
  • 是否需要幂等设计
  • 是否包含测试用例

R7.4 CI 流水线

stages: [lint, test, security, build, docker]

# lint:     ESLint + Checkstyle
# test:     mvn test + jacoco (coverage > 50%)
# security: OWASP dependency-check + SpotBugs + secretlint
# build:    mvn package + docker build
# docker:   push to registry

8. 日志与异常处理规范

R8.1 日志级别

级别场景示例
ERROR系统异常、需要人工介入数据库连接失败、支付回调异常
WARN可恢复的错误、降级行为外部 API 超时、lilishop 同步失败
INFO关键业务流程节点登录成功、订单创建、CP 审核
DEBUG调试信息请求参数、SQL 执行

R8.2 异常处理

  • 业务异常统一抛出 BizException(code, message)
  • GlobalExceptionHandler 自动转换为 Result.fail()
  • 禁止捕获异常后仅 e.printStackTrace(),必须 log.error("上下文", e)
  • 不允许 catch (Exception ignored) {} 吞异常(外部 RPC 降级除外)

R8.3 敏感数据脱敏

  • 日志中禁止打印完整手机号、Token、密码
  • 手机号脱敏: 138****1234
  • Token 脱敏: eyJh...(仅打印前 8 位)

R8.4 审计日志

以下操作必须记录审计日志(t_audit_log):

  • 管理员操作: CP审核、用户封禁、内容上下架、提现审批
  • 金币/资金变动: 充值、消费、提现(已有 t_coin_transaction)
  • 配置变更: 支付费率、广告位、提现档位

整改优先级

#等级问题规范条款预计工时
1P0Controller 内 JDBC 直连(8+处)R1.2 / R4.12h
2P0裸线程创建(6+处)R1.22h
3P0密钥/密码硬编码R5.13h
4P0支付回调签名验证 placeholderR5.24h
5P0金币无分布式锁R4.33h
6P1Commit 规范 + 分支策略R7.1 / R7.21h
7P1测试补齐(金币/支付/风控)R6.28h
8P1JWT 缩短有效期 + 黑名单R5.22h
9P2CI 流水线搭建R7.44h
10P2审计日志补齐R8.44h

预估总工时: 33h (约 4 人天),建议分 2 周迭代完成。

Generated by DeepSeek TUI v0.8.18 | 2026-07-21