jxust-yqlx-server

GoJxust V1.4.0

GoJxust 是专为江西理工大学学生设计的开源自托管校园服务平台，现本项目为江理一起来学小程序的后端服务。从学习与生活中的常见需求出发，提供一系列提高效率、降低信息差的服务，帮助大学生节约时间、提升自我。

功能亮点

核心架构

校园服务

管理与运维

技术栈

项目结构

goJxust/
├── cmd/apiserver/          # 应用入口
│   ├── main.go             # 主程序
│   ├── .env.example        # 环境变量模板
│   └── Dockerfile
├── internal/
│   ├── bootstrap/          # 启动初始化
│   ├── config/             # 配置管理
│   ├── database/           # 数据库连接与迁移
│   ├── handlers/           # HTTP 处理器（Controller）
│   ├── services/           # 业务逻辑层
│   ├── models/             # 数据模型（GORM）
│   ├── dto/                # 请求/响应 DTO
│   ├── middleware/         # 中间件（认证、RBAC、幂等等）
│   ├── router/             # 路由注册
│   ├── scheduler/          # 定时任务
│   ├── worker/             # 异步任务
│   └── pkg/                # 内部公共包
├── pkg/
│   ├── constant/           # 全局常量
│   ├── logger/             # 日志封装
│   ├── minio/              # MinIO 客户端
│   └── utils/              # 工具函数
├── docs/                   # 设计文档与 API 文档
├── scripts/                # SQL 初始化、E2E 测试等脚本
├── deployment/             # Kubernetes 部署配置
├── Makefile
└── docker-compose.yml

快速开始

环境要求

• Go 1.26+
• MySQL 8.0+
• Redis（幂等性、缓存等功能依赖）
• MinIO（文件存储，可选）

1. 克隆项目

git clone https://github.com/TogetherForStudy/jxust-yqlx-server.git
cd jxust-yqlx-server

2. 环境配置

cp cmd/apiserver/.env.example .env
vim .env    # 填写数据库、Redis、微信小程序等配置

3. 安装依赖

go mod tidy

4. 启动服务

go run cmd/apiserver/main.go

应用默认在 http://localhost:8080 启动。

部署

Docker

make docker-build                   # 构建镜像
docker run -p 8080:8080 gojxust     # 运行容器

Docker Compose

docker-compose up -d

Kubernetes

配置文件位于 deployment/ 目录。

开发指南

常用命令

make build-apiserver    # 构建 Linux 二进制
make test               # 运行单元测试
make test-coverage      # 测试 + 覆盖率
make clean              # 清理构建产物

E2E 测试

# 初始化 RBAC 数据（首次）
mysql -u user -p database < scripts/init_rbac.sql

# 安装依赖
pip install httpx

# 运行（需先启动服务，且 GIN_MODE 非 release）
python scripts/e2e_test.py

添加新接口

1. internal/dto/ — 定义请求/响应结构体
2. internal/models/ — 添加数据模型（如需）
3. internal/services/ — 实现业务逻辑
4. internal/handlers/ — 编写 Handler
5. internal/router/router.go — 注册路由与中间件
6. 按需在 RBAC 中配置权限标签

换行符规范

项目统一使用 LF 换行符，已通过 .gitattributes 强制配置。

贡献指南

1. Fork 本仓库

2. 基于 main 创建特性分支

3. 遵循 Conventional Commits 提交

4. 推送分支并创建 Pull Request

   a. 管理员会随时审核您的代码,除非你的PR设置为draft状态或标题内包含WIP/Work In Progress/🚧字样，当然，你也可以手动at管理员/召唤gemini来review你的代码

许可证

MIT License