rustzen-admin 全栈管理后台起始模板

🧩 rustzen-admin：全栈管理后台起始模板

前言

在开发管理后台系统时，我们经常需要搭建相似的基础架构：用户认证、CRUD 操作、API 文档等。为了减少重复工作，我创建了 rustzen-admin - 一个基于 Rust + React 的全栈管理后台起始模板。

🎯 项目定位

这是一个起始模板，而不是完整的产品。它提供：

基础架构 - 前后端分离的项目结构
开发环境 - Docker 容器化的开发配置
代码组织 - 模块化的代码架构模式
文档体系 - 完整的开发和 API 文档

🛠️ 技术选型

后端技术栈

Rust + Axum - Web 框架，注重性能和类型安全
SQLx - 数据库操作，编译期 SQL 检查
PostgreSQL - 关系型数据库
Tokio - 异步运行时

前端技术栈

React 19 + TypeScript - 现代化前端框架
Vite - 快速构建工具
Ant Design Pro - 企业级 UI 组件库
TailwindCSS - 原子化 CSS 框架
SWR - 数据获取和缓存

🏗️ 项目结构

bash 复制代码

rustzen-admin/
├── backend/         # Rust 后端服务
├── frontend/        # React 前端应用
├── docker/          # Docker 配置
├── docs/            # 项目文档
├── justfile         # 统一命令管理
└── README.md

后端模块化设计

每个功能模块遵循统一的架构模式：

rust 复制代码

features/
├── user/
│   ├── model.rs      // 数据模型定义
│   ├── repo.rs       // 数据库操作层
│   ├── service.rs    // 业务逻辑层
│   ├── routes.rs     // 路由处理层
│   └── mod.rs        // 模块导出

这种分层架构的优势：

职责清晰 - 每层只关注自己的职责
易于测试 - 可以独立测试每一层
便于维护 - 修改某层不影响其他层

✨ 当前功能

🔧 开发环境

Docker 容器化开发环境
前后端热重载
统一的命令管理（justfile）
环境变量配置管理

🗃️ 后端基础

模块化架构设计
PostgreSQL 数据库集成
CORS 和日志中间件
结构化错误处理
Mock 数据接口 - 支持前端独立开发

🎨 前端脚手架

React + TypeScript 应用
UI 组件库集成
路由系统搭建
状态管理基础
类型安全的 API 集成 - 基于 SWR 的数据获取

🔄 类型安全与开发体验

前后端类型严格对齐 - 确保数据结构一致性
Mock 数据驱动前后端联调 - 前端可独立开发，无需等待后端完成
编译期类型检查 - TypeScript 和 Rust 在编译期捕获错误
AI 工具友好 - 清晰的代码结构，便于现代开发工具辅助

📚 文档体系

API 文档和测试示例
开发环境搭建指南
架构设计说明

🚀 快速开始

环境要求

Rust 1.70+
Node.js 24+ (推荐使用 LTS 版本)
Docker 容器环境
just 命令运行器

安装步骤

bash 复制代码

# 1. 克隆项目
git clone https://github.com/idaibin/rustzen-admin.git
cd rustzen-admin

# 2. 配置环境变量
cp backend/.env.example backend/.env

# 3. 安装前端依赖
cd frontend && pnpm install && cd ..

# 4. 启动开发环境
just dev

一条命令 just dev 会自动：

启动 PostgreSQL 数据库
启动 Rust 后端服务（热重载）
启动 React 前端服务（热重载）
打开浏览器访问 http://localhost:5173

💡 代码示例

类型安全的 API 契约

前后端共享相同的类型定义，确保数据一致性：

rust 复制代码

// 后端：Rust 类型定义
#[derive(Debug, Serialize, Deserialize)]
pub struct User {
    pub id: Uuid,
    pub username: String,
    pub email: String,
    pub created_at: DateTime<Utc>,
}

typescript 复制代码

// 前端：TypeScript 类型定义（自动生成或手动同步）
interface User {
  id: string;
  username: string;
  email: string;
  created_at: string;
}

错误处理模式

rust 复制代码

#[derive(Debug, thiserror::Error)]
pub enum UserError {
    #[error("用户不存在: {id}")]
    NotFound { id: Uuid },
    #[error("数据库错误: {0}")]
    Database(#[from] sqlx::Error),
}

Repository 模式

rust 复制代码

#[async_trait]
pub trait UserRepository {
    async fn find_by_id(&self, id: Uuid) -> Result<Option<User>, UserError>;
    async fn create(&self, user: CreateUser) -> Result<User, UserError>;
}

📱 适用场景

适合的项目类型

企业内部管理系统
SaaS 产品后台
内容管理系统
数据管理平台

不适合的场景

简单的静态网站
高实时性要求的应用
复杂的游戏后端

🔮 后续规划

这个模板可以在以下方向扩展：

JWT 身份认证实现
基于角色的权限控制
文件上传功能
更丰富的 UI 组件
单元测试覆盖
从 Mock 数据迁移到真实数据库持久化

欢迎参与共建！ 我们欢迎 Issue 和 Pull Request，项目路线图由社区驱动。

🤝 参与贡献

项目采用 MIT 开源协议，欢迎贡献：

贡献方式

🐛 问题反馈 - 发现 bug 请提交 Issue
💡 功能建议 - 新功能想法欢迎讨论
📝 文档改进 - 帮助完善项目文档
🔧 代码贡献 - 提交 Pull Request
🏢 实际使用反馈 - 分享真实项目使用经验

开发规范

遵循 Rust 官方代码风格
前端使用 ESLint + Prettier
提交信息遵循 Conventional Commits

🎉 总结

rustzen-admin 是一个起始模板，不是完整的产品。它提供了：

清晰的项目结构 - 便于理解和扩展
现代化的技术栈 - Rust + React 的组合
完善的开发环境 - 开箱即用的开发配置
良好的代码组织 - 模块化的架构设计
类型安全的全栈开发 - 前后端类型严格对齐
Mock 数据驱动的前后端联调 - 提升团队协作效率

当前版本包含 Mock 数据接口，支持前端快速开发，同时后端架构逐步完善。这种方式让团队可以并行工作，快速迭代。

如果你正在寻找一个 Rust + React 的全栈项目起点，这个模板可能会为你节省一些初始搭建时间。

🔗 相关链接

GitHub 仓库 : github.com/idaibin/rus...
在线文档 : github.com/idaibin/rus...
当前版本: v0.1.0

欢迎交流讨论！如果你有任何建议或问题，请在 GitHub 上提交 Issue。🦀⚛️

标签: #Rust #React #全栈开发 #管理后台 #开源项目