readme
# Web 后端项目 README
本项目是一个基于 **Colleen 框架 + jOOQ + PostgreSQL + Cleary 调度库** 构建的现代 Web 后端服务，采用 **环境变量驱动配置**，支持多环境部署（dev / prod / local）。
该架构具有以下特点：
* 类型安全的数据库访问（jOOQ）
* 高性能 PostgreSQL
* 轻量级 Web 框架（Colleen）
* 强大的任务调度系统（Cleary）
* 零侵入环境配置管理（.env 文件体系）
---
# 目录
* [技术栈](#技术栈)
* [项目结构](#项目结构)
* [环境配置](#环境配置)
* [运行项目](#运行项目)
* [数据库代码生成 (jOOQ)](#数据库代码生成-jooq)
* [任务调度 (Cleary)](#任务调度-cleary)
* [多环境加载机制](#多环境加载机制)
* [部署](#部署)
* [最佳实践](#最佳实践)
---
# 技术栈
| 组件 | 说明 |
| ---------- | ------------- |
| Colleen | Kotlin Web 框架 |
| PostgreSQL | 主数据库 |
| jOOQ | 类型安全 SQL 代码生成 |
| Cleary | 任务调度库 |
| Kotlin | 主语言 |
| dotenv | 环境变量加载 |
---
# 项目结构
```
project-root/
│
├─ src/
│ ├─ main/
│ │ ├─ kotlin/
│ │ │ ├─ config/ # 配置加载
│ │ │ ├─ routes/ # HTTP 路由
│ │ │ ├─ services/ # 业务逻辑
│ │ │ ├─ tasks/ # Cleary 调度任务
│ │ │ ├─ jooq/ # jOOQ 生成代码
│ │ │ └─ Main.kt # 应用入口
│ │ │
│ │ └─ resources/
│ │ ├─ static/ # 静态资源 (html/js/css)
│ │ └─ logback.xml # 日志配置
│
├─ .env
├─ .env.dev
├─ .env.prod
├─ .env.local
│
├─ pom.xml
└─ README.md
```
```
---
# 环境配置
本项目使用 `.env` 文件进行配置管理。
支持以下环境文件：
```
.env
.env.dev
.env.prod
.env.local
```
示例：
```
DB_URL=jdbc:postgresql://localhost:5432/app
DB_USER=postgres
DB_PASSWORD=postgres
SERVER_PORT=8080
COLLEEN_ENV=dev
```
---
# 运行项目
## 1. 设置环境变量
例如：
Mac / Linux
```
export COLLEEN_ENV=dev
```
Windows
```
set COLLEEN_ENV=dev
```
---
## 2. 构建项目
```
mvn clean package
```
---
## 3. 启动服务
```
java -jar target/app.jar
```
```
---
# 数据库代码生成 (jOOQ)
本项目使用 jOOQ 自动生成数据库访问代码。
生成命令：
```
mvn generate-sources
```
生成位置：
```
src/main/kotlin/jooq/
```
使用示例：
```kotlin
val users = ctx
.selectFrom(USERS)
.where(USERS.ID.eq(id))
.fetchOne()
```
优势：
* 完全类型安全
* 无字符串 SQL
* 自动补全
* 编译期错误检查
* 编译期错误检查
---
# 任务调度 (Cleary)
Cleary 用于执行：
* 定时任务
* Cron 任务
* 后台任务
示例：
```kotlin
val scheduler = TaskScheduler {
autoStart = true
}
scheduler.task("heartbeat") {
every(10.seconds)
run {
println("heartbeat")
}
}
```
Cron 示例：
```kotlin
scheduler.task("cleanup") {
cron("0 0 * * * *")
run {
cleanupDatabase()
}
}
```
---
# 多环境加载机制
环境由：
```
COLLEEN_ENV
```
决定。
加载顺序：
```
.env
.env.{COLLEEN_ENV}
.env.local
```
示例：
```
COLLEEN_ENV=prod
```
加载：
```
.env
.env.prod
.env.local
```
优先级：
```
.env.local (最高)
.env.prod
.env
```
这允许：
* 默认配置
* 环境特定配置
* 本地覆盖
---
# 部署
生产环境：
```
export COLLEEN_ENV=prod
java -jar app.jar
```
推荐：
* 使用 Docker
* 使用 systemd
* 使用 Kubernetes
---
# 最佳实践
推荐：
* 不要提交 `.env.local`
* 提交 `.env.example`
* 使用 `.env.prod` 用于生产
示例：
```
.env.example
```
```
DB_URL=
DB_USER=
DB_PASSWORD=
```
---
# 总结
本项目提供：
* 类型安全数据库访问
* 强大任务调度
* 灵活环境配置
* 清晰架构
适用于：
* Web 后端
* API 服务
* 定时任务系统
* 微服务
---
# License
MIT