目录说明

在开始阅读项目源码之前，先了解一下整体的目录结构会更容易建立全局认知。

一个清晰的目录设计，不只是为了“好看”，更重要的是在项目逐渐变复杂之后，依然能够保持良好的可维护性和可扩展性。

下面是 OneAdmin 的完整目录结构：

.
├── bin/                        # 编译产物目录  (存放构建生成的可执行文件)
├── cmd/                        # 应用入口  (各类服务或命令的启动入口)
├── docs/                       # API 文档  (Swagger / OpenAPI 生成文件)
├── internal/                   # 内部应用代码  (核心实现，不对外暴露)
│   ├── bootstrap               # 应用初始化  (依赖注入、组件注册、容器构建等)
│   ├── config                  # 配置管理  (配置结构定义与加载，支持多环境)
│   ├── dto                     # 数据传输对象  (请求与响应结构定义)
│   │   ├── input               # 请求参数结构体定义
│   │   └── resp                # 响应数据结构体定义
│   ├── enum                    # 枚举定义  (统一管理业务枚举类型)
│   ├── handler                 # 接口层  (HTTP 请求处理、参数解析与响应封装)
│   │   ├── 模块A
│   │   │   ├── common.go       # 模块通用方法  (如数据转换、辅助处理等)
│   │   │   └── handler.go      # HTTP 请求处理逻辑
│   │   ├── 模块B
│   │   │   ├── common.go       # 模块通用方法  (如数据转换、辅助处理等)
│   │   │   └── handler.go      # HTTP 请求处理逻辑
│   ├── i18n                    # 国际化支持  (多语言资源、错误码与翻译逻辑)
│   ├── logger                  # 日志模块  (统一日志接口与实现封装)
│   ├── middleware              # 中间件  (认证、日志、跨域、限流等)
│   ├── migrate                 # 数据库迁移  (结构变更与版本管理)
│   ├── model                   # 数据模型  (ORM 映射结构体定义)
│   ├── repository              # 数据访问层  (数据库操作封装)
│   │   ├── 数据模型A
│   │   │   ├── gorm_repo.go    # 仓储实现  (基于 GORM 的数据操作)
│   │   │   └── interface.go    # 仓储接口定义  (抽象数据访问行为)
│   │   ├── 数据模型B
│   │   │   ├── gorm_repo.go    # 仓储实现  (基于 GORM 的数据操作)
│   │   │   └── interface.go    # 仓储接口定义  (抽象数据访问行为)
│   ├── response                # 响应封装  (统一 API 返回结构与方法)
│   ├── service                 # 业务层  (核心业务逻辑编排与实现)
│   │   ├── 业务分类A
│   │   │   ├── common.go       # 业务通用方法  (基础功能拆分与复用)
│   │   │   ├── dto.go          # 业务内部 DTO (解耦 handler 与 service)
│   │   │   └── service.go      # 业务逻辑编排  (不直接操作数据库)
│   │   ├── 业务分类B
│   │   │   ├── common.go       # 业务通用方法  (基础功能拆分与复用)
│   │   │   ├── dto.go          # 业务内部 DTO (解耦 handler 与 service)
│   │   │   └── service.go      # 业务逻辑编排  (不直接操作数据库)
│   ├── validation              # 参数校验  (请求参数校验规则与实现)
│   └── webui                   # 前端构建产物  (嵌入式静态资源)
├── logs/                       # 日志目录  (运行时日志文件输出位置)
├── pkg/                        # 公共库  (通用工具包，可对外复用)
│   ├── crypto/                 # 加密工具  (密码处理、加解密等)
│   ├── jwt/                    # JWT 工具  (认证、解析、签发等)
│   ├── ptr/                    # 指针工具  (基础类型指针辅助方法)
│   └── timeutil/               # 时间工具  (格式化、计算等)
├── web/                        # 前端源码  (后台管理系统项目)
├── .gitignore                  # Git 忽略配置
├── config.example.yaml         # 配置示例  (用于初始化项目配置)
├── go.mod                      # Go 模块定义文件
├── go.sum                      # Go 依赖校验文件
├── LICENSE                     # 开源协议说明
├── Makefile                    # 构建脚本  (编译、运行、部署等命令)
└── README.md                   # 项目说明文档

php

初看这个目录，可能会觉得有点“多”，甚至有点复杂。但其实在日常开发过程中，你并不需要关心所有目录。

绝大多数业务开发，主要集中在 internal 目录下，而且核心只围绕一条非常清晰的链路展开：

DTO → Handler → Service → Repository → Model

你可以把它理解为一个简化版的 DDD 分层实践：

DTO：负责请求与响应的数据结构定义（对外）
Handler：处理 HTTP 请求，做参数解析与响应返回
Service：负责业务逻辑编排（核心层）
Repository：封装数据访问（数据库操作）
Model：定义数据库模型结构

这一套结构的目标很明确：解耦 + 清晰职责 + 易维护

另外，模块之间的依赖关系，并不是在各处随意创建的，而是统一在 bootstrap 中完成：

依赖注入
组件初始化
服务注册

也就是说，所有“组装工作”都集中在一个地方完成，业务代码本身只关注逻辑，不关心依赖是如何来的。

至于更具体的内容，例如：

接口是如何一步步开发出来的
请求是如何流转到各层的
配置文件是如何加载的
依赖注入的完整流程

这些我会在后续的文档中单独展开讲，这一篇主要是帮助你先建立整体认知。

评论似乎卡住了，尝试刷新？✨

快速上手

后端开发

前端开发