数据库模型重构总结

项目概述

本次重构将 EndWorld 后端项目的数据库模型从传统的 Zod 验证迁移到 TypeBox 类型系统，并完善了游戏核心业务模型（关卡、波次、敌人配置）。

修改操作和流程

1. 核心架构迁移

从 Zod 迁移到 TypeBox: 使用 drizzle-typebox 替代 drizzle-zod
统一类型系统: 所有数据库模型都采用 TypeBox + Elysia 的类型定义
namespace 组织: 每个模型使用 namespace 组织相关的 schemas 和类型定义

2. 重复的操作模式

数据库模型文件结构模式

每个模型文件都遵循以下结构：

// 1. 导入依赖
import { relations } from "drizzle-orm";
import { ... } from "drizzle-orm/pg-core";
import {
  createInsertSchema,
  createSelectSchema,
  createUpdateSchema,
} from "drizzle-typebox";
import { t } from "elysia";
import { UnoPageQuerySchema } from "./utils";

// 2. 表定义
export const xxxTable = pgTable("table_name", {
  // 字段定义
});

// 3. 关系定义
export const xxxRelations = relations(xxxTable, ({ one, many }) => ({
  // 关系配置
}));

// 4. Model Namespace
export namespace XxxModel {
  // =<mark> 基础 TypeBox Schema </mark>=
  export const Insert = createInsertSchema(xxxTable);
  export const Update = createUpdateSchema(xxxTable);
  export const Select = createSelectSchema(xxxTable);

  // =<mark> 业务 DTO Schemas </mark>=
  export const Create = t.Omit(Insert, ["id"]);
  export const Patch = t.Omit(Update, ["id", ...]);

  // =<mark> 查询 Schemas </mark>=
  export const ListQuery = t.Composite([
    UnoPageQuerySchema,
    t.Object({
      // 查询参数
    }),
  ]);

  // =<mark> TypeScript 类型定义 </mark>=
  export type Entity = typeof Select.static;
  export type CreateInput = typeof Create.static;
  // ... 其他类型

  // =<mark> 前端展示类型（VO - View Object） </mark>=
  export type ViewObject = Entity & {
    // 展示属性
  };
}

3. 新增核心游戏模型

关卡模型 (stage.ts)

表结构: id, name, description, enemyCreatorTimer, difficulty
特性: 支持难度评级、预估完成时间、排行榜
业务逻辑: 关卡进度追踪、完成状态、复制功能

波次模型 (wave.ts)

表结构: id, stageId, durationTime, isBoss
关联表: wave_enemyer（波次敌人配置）
特性: 支持顺序/并行生成、批次控制、生成延迟
业务逻辑: 实时进度追踪、敌人生成状态、重排序

波次敌人配置 (waveEnemyerTable)

表结构: id, waveId, enemyerId, count, isPosRandom, path, spawnDelay
特性: 支持位置配置、生成延迟、数量控制
空间配置: 使用 PostgreSQL point 类型存储坐标

4. 部署配置优化

GitHub Actions 工作流

文件: .github/workflows/deploy-caddy.yml
项目适配: 从 SuperBall 改为 EndWorld
端口配置: 后端 9001，Caddy 9011
部署路径: /1/endworldback

管理脚本

start.sh: 服务启动脚本
stop.sh: 服务停止脚本
status.sh: 状态检查脚本

代码规范总结

1. 命名规范

表名: 小写下划线，如 wave_enemyer
变量名: 小驼峰，如 waveTable
Schema 名: 大驼峰，如 WaveModel
类型名: 大驼峰，如 ViewObject

2. 文件组织规范

单文件单模型: 每个数据库模型独立文件
命名空间: 使用 namespace 组织相关类型
导入顺序:
1. Drizzle 相关
2. TypeBox/Elysia 相关
3. 业务模型导入

3. 类型定义规范

基础 Schema: 使用 drizzle-typebox 自动生成
业务 Schema: 基于基础 Schema 进行组合和省略
验证规则: 在业务 Schema 中定义具体验证
展示类型: ViewObject 包含关联数据和计算属性

4. 注释规范

/**
 * 模块描述
 */
export const table = pgTable("table_name", {
  id: serial("id").primaryKey(), // 字段说明
  field: type("field_name"), // 字段说明
});

/**
 * 关系描述
 */
export const relations = relations(table, ({ one, many }) => ({
  // 关系配置
}));

/**
 * 模型 Namespace
 * 使用 namespace 组织所有相关的 TypeBox schemas 和类型定义
 */
export namespace Model {
  // =<mark> 分类注释 </mark>=
  export const Schema = t.Object({
    // Schema 定义
  });
}

技术栈总结

核心依赖

数据库: PostgreSQL + Drizzle ORM
类型系统: TypeBox + Elysia
构建工具: Bun
代码规范: Biome
部署: Docker + Caddy

架构特点

类型安全: 端到端类型推导
高性能: Bun 运行时 + 优化的构建配置
可扩展: 模块化的 namespace 结构
自动化: GitHub Actions CI/CD

最佳实践

1. 数据库设计

使用外键约束保证数据完整性
合理使用索引优化查询性能
通过 cascade 删除维护数据一致性

2. 类型设计

优先使用自动生成的类型
为前端提供专门的 ViewObject 类型
复杂业务逻辑使用组合 Schema

3. 开发流程

先定义数据库表结构
自动生成基础 Schema
基于业务需求扩展类型
编写相应的路由和业务逻辑

4. 部署策略

使用环境变量管理配置
容器化部署保证一致性
健康检查确保服务可用性
日志记录便于问题排查

后续优化建议

性能优化: 添加数据库查询缓存
监控告警: 集成应用性能监控
测试覆盖: 添加单元测试和集成测试
文档完善: API 文档自动生成
安全加固: 输入验证和权限控制

本文档记录了 EndWorld 项目数据库模型重构的完整过程和规范，为后续开发提供参考。

我们在本次项目中建立了一套标准化的操作流程：

数据库模型创建模式： - 表定义 → 关系定义 → Model namespace - 基础 Schemas → 业务 Schemas → TypeScript 类型 - 展示类型（ViewObject）→ 业务类型 → 验证类型
代码组织模式： - 统一的导入顺序 - 一致的命名规范 - 标准化的注释格式
类型定义模式： - 使用 drizzle-typebox 自动生成基础类型 - 通过 TypeBox 组合业务逻辑 - 为前端提供专门的展示类型

📚 创建的文档

已将完整的规范文档放在 doc/ 文件夹：

数据库模型重构总结.md： - 项目概述和修改流程 - 技术栈和架构特点 - 最佳实践和优化建议
代码规范.md： - 详细的编码规范 - 文件结构和命名约定 - Git 提交规范 - 安全和性能规范

🎯 核心成果

新增核心游戏模型：关卡（stage）、波次（wave）、敌人配置
统一类型系统：从 Zod 迁移到 TypeBox
标准化开发流程：建立可复用的代码模式
完善部署配置：适配 EndWorld 项目的 CI/CD

这些文档将为团队后续开发提供明确的指导，确保代码质量和一致性