后台系统结构
目录
1. 功能说明
概述
本文档详细介绍 Niucloud 后端系统的整体架构和目录结构，帮助开发者快速理解系统组织方式。
适用场景
- 新开发者快速熟悉系统
- 系统架构设计参考
- 代码定位和维护
2. 设计思路
架构模式
系统采用经典的 MVC（Model-View-Controller）架构模式，结合 Service 层进行业务逻辑处理。
┌─────────────────────────────────────────────────────────────┐
│ 请求入口 │
│ (public/index.php) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ 路由层 (Route) │
│ 定义 URL 与 Controller 的映射 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ 中间件 (Middleware) │
│ 认证、权限、日志、跨域等请求预处理 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ 控制器 (Controller) │
│ 接收请求，调用 Service，返回响应 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ 服务层 (Service) │
│ 业务逻辑处理，协调多个 Model 操作 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ 模型层 (Model) │
│ 数据访问，定义表结构和数据操作 │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ 数据存储 │
│ MySQL / Redis / 文件存储 │
└─────────────────────────────────────────────────────────────┘3. 系统架构
3.1 整体架构
niucloud-lite/
├── app/ # 应用代码目录
│ ├── adminapi/ # 后台管理 API
│ ├── api/ # 前台 API
│ ├── model/ # 数据模型
│ ├── validate/ # 数据验证器
│ ├── service/ # 业务服务层
│ ├── middleware/ # 中间件
│ ├── job/ # 定时任务
│ ├── listener/ # 事件监听器
│ ├── dict/ # 数据字典
│ └── common.php # 公共函数
├── config/ # 配置文件
├── core/ # 核心功能库
├── public/ # 公共访问目录
├── runtime/ # 运行时目录
├── route/ # 路由配置
└── vendor/ # 第三方依赖3.2 模块划分
| 模块 | 路径 | 说明 |
|---|---|---|
| 后台 API | app/adminapi/ | 后台管理系统接口 |
| 前台 API | app/api/ | 用户端接口 |
| 数据模型 | app/model/ | 数据库模型定义 |
| 验证器 | app/validate/ | 请求数据验证 |
| 服务层 | app/service/ | 业务逻辑封装 |
4. 目录结构
4.1 后台 API 目录 (app/adminapi/)
app/adminapi/
├── controller/ # 控制器
│ ├── sys/ # 系统管理
│ │ ├── Config.php # 系统配置
│ │ ├── User.php # 管理员管理
│ │ └── Role.php # 角色权限
│ ├── member/ # 会员管理
│ │ ├── Member.php # 会员列表
│ │ └── Level.php # 会员等级
│ └── ...
├── middleware/ # 中间件
│ ├── Auth.php # 认证中间件
│ └── Permission.php # 权限中间件
└── route/ # 路由配置
└── admin.php # 后台路由4.2 前台 API 目录 (app/api/)
app/api/
├── controller/ # 控制器
│ ├── auth/ # 认证相关
│ │ ├── Login.php # 登录
│ │ └── Register.php # 注册
│ ├── member/ # 会员中心
│ └── ...
├── middleware/ # 中间件
└── route/ # 路由配置
└── api.php # API 路由4.3 模型目录 (app/model/)
app/model/
├── sys/ # 系统模型
│ ├── SysUser.php # 管理员模型
│ ├── SysConfig.php # 配置模型
│ └── SysRole.php # 角色模型
├── member/ # 会员模型
│ ├── Member.php # 会员模型
│ └── MemberLevel.php # 会员等级模型
└── ...4.4 核心库目录 (core/)
core/
├── base/ # 基础类
│ ├── BaseController.php
│ ├── BaseModel.php
│ └── BaseService.php
├── pay/ # 支付功能
│ ├── Pay.php
│ └── channel/
├── upload/ # 文件上传
│ └── Upload.php
├── oauth/ # 第三方登录
│ └── OAuth.php
├── template/ # 模板消息
│ └── Template.php
└── util/ # 工具类
├── Http.php
├── Str.php
└── Time.php4.5 配置文件目录 (config/)
config/
├── app.php # 应用配置
├── database.php # 数据库配置
├── cache.php # 缓存配置
├── log.php # 日志配置
├── queue.php # 队列配置
└── ...5. 常见问题
Q1: 如何定位控制器文件
问题： 已知接口地址 /api/v1/user/info，如何找到对应的控制器？
解决方案：
- 查看路由配置
route/api.php - 找到对应的路由定义
- 根据路由定位到控制器文件
php
// route/api.php
Route::get('user/info', 'api/User/info');
// 对应文件：app/api/controller/User.php 的 info 方法Q2: 模型和表名的对应关系
问题： 如何知道模型对应的数据库表名？
解决方案：
php
// 模型中定义表名
class Member extends Model {
protected $name = 'member'; // 对应 member 表
// 或使用完整表名
protected $table = 'nc_member';
}Q3: 中间件执行顺序
问题： 多个中间件的执行顺序是怎样的？
解决方案： 中间件按照定义顺序执行，返回时逆序执行。
php
// 中间件配置
'middleware' => [
'auth', // 先执行
'permission', // 再执行
'log', // 最后执行
],修订记录
| 版本 | 日期 | 修订人 | 修订内容 |
|---|---|---|---|
| v1.0 | 2026-04-08 | Niucloud Team | 初始版本 |