LyEdu 后端开发指南
编辑日期：2026-02-26
基于 ly-edu 项目结构整理
一、后端项目概览
LyEdu 提供双后端架构，可按团队技术栈任选其一或对照使用：
| 实现 | 目录 | 技术栈 | 端口 | 说明 |
|---|---|---|---|---|
| Java | lyedu-api | Spring Boot 4、JDK 25、MyBatis Plus、MySQL、Flyway | 8080 | 传统 Java 技术栈 |
| Python | lyedu-api-python | FastAPI、SQLAlchemy、MySQL、Alembic | 9700 | 推荐，更新更活跃 |
接口设计保持一致，数据库共用 db/ 下的迁移脚本。
二、开发环境准备
公共依赖
- MySQL：8.0+
- Redis：可选，用于会话/缓存
- Docker & Docker Compose：可选，快速启动 MySQL + Redis
启动 MySQL + Redis（Docker）
bash
docker compose -f scripts/docker/compose-mysql-redis.yml up -d若使用自有 MySQL/Redis，可跳过此步，直接在配置中填写连接信息。
三、Python 后端（推荐）
环境要求
- Python 3.10+
- 虚拟环境（venv）
启动步骤
bash
cd lyedu-api-python
# 创建虚拟环境
python -m venv .venv
# 激活（Windows）
.\.venv\Scripts\activate
# 激活（Linux / Mac）
# source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 复制环境变量
cp .env.example .env.dev # 或 .env
# 修改 .env.dev 中的 database / redis 等配置
# 数据库迁移（首次或 schema 变更后）
alembic -c alembic.ini upgrade head
# 启动服务
ENV=dev uvicorn main:app --reload --host 0.0.0.0 --port 9700- API 文档：http://localhost:9700/api-docs
- 数据库配置：
database.url等，见configuration.md
一键启动
使用项目脚本（会先迁移再启动）：
powershell
.\scripts\dev\start.ps1在 scripts/dev/dev-config.yml 中配置 start_lyedu_api_python: true 及数据库连接。
四、Java 后端
环境要求
- JDK 25
- Gradle（项目含 Wrapper）
构建与启动
bash
cd lyedu-api
# 初始化 Gradle Wrapper（首次）
.\init-gradle.ps1 # Windows
# 或手动: gradle wrapper
# 构建 jar
.\build-api.ps1 # Windows
# 或 ./build-api.sh # Linux / Mac
# 或 ./gradlew bootJar
# jar 输出到 pkg/lyedu-api.jar启动方式：
- IDE：运行
Application主类，--spring.profiles.active=dev - 命令行：
java -jar pkg/lyedu-api.jar --spring.profiles.active=dev - Docker：见
deployment.md
数据库配置在 application.yml 中。
五、数据库与迁移
统一迁移目录
- Java / Flyway：
db/flyway/ - Python / Alembic：
db/alembic/
详细说明见 db/README.md。
Python 迁移命令
bash
cd lyedu-api-python
# 升级到最新
alembic -c alembic.ini upgrade head
# 生成迁移
alembic -c alembic.ini revision --autogenerate -m "描述"
# 回滚
alembic -c alembic.ini downgrade -1Java 迁移
Flyway 随应用启动自动执行，只需保证 db/flyway/ 下脚本符合规范。
六、项目结构（Python 示例）
lyedu-api-python/
├── main.py # FastAPI 入口
├── alembic.ini # Alembic 配置
├── requirements.txt
├── .env.example
├── app/
│ ├── api/ # 路由
│ ├── core/ # 配置、安全
│ ├── models/ # ORM 模型
│ ├── schemas/ # Pydantic 模型
│ └── services/ # 业务逻辑
└── alembic/
└── versions/七、认证与授权
- JWT：登录后返回 token，请求头
Authorization: Bearer <token> - 飞书登录：OAuth2 流程，回调后生成 JWT
- 权限：基于角色（RBAC），接口有权限注解/依赖
八、开发建议
- 环境变量：敏感信息放
.env，勿提交仓库 - 迁移：改表结构先写迁移，再改代码
- 接口：与前端约定路径、请求/响应格式，可参考 Swagger
- 日志：统一使用 logging，区分 dev/prod 级别