基于Gofiber的Docker化MariaDB清洁架构实践指南

基于Gofiber的Docker化MariaDB清洁架构实践指南

recipes 📁 Examples for 🚀 Fiber 项目地址: https://gitcode.com/gh_mirrors/rec/recipes

项目概述

本文将深入探讨如何基于Gofiber框架构建一个采用清洁架构(Clean Architecture)的RESTful API应用，并使用Docker容器化的MariaDB作为数据库解决方案。这个示例项目展示了现代Go语言开发中的多个重要实践：

1. 清洁架构在Go项目中的具体实现
2. Docker与MariaDB的集成使用
3. 基于JWT的身份验证机制
4. 1对多关系型数据映射
5. 使用Makefile实现项目自动化管理

技术栈要求

在开始之前，请确保您的开发环境中已安装以下工具：

• Docker及Docker Compose：用于容器化部署
• 支持sh、make和curl的Shell环境：用于自动化测试(UNIX系统或WSL均可)
• Postman(可选)：用于API接口测试

架构设计解析

清洁架构核心思想

清洁架构由Robert C. Martin(Uncle Bob)提出，其核心目标是实现关注点的完全分离。采用这种架构的系统具有以下优势：

1. 框架独立性：不绑定特定框架
2. 可测试性：便于编写单元测试
3. UI独立性：业务逻辑不依赖界面
4. 数据库独立性：可轻松更换数据存储方案
5. 外部依赖独立性：核心业务不依赖外部服务

关键原则是依赖规则：源代码依赖只能向内指向。内层不应了解外层的任何信息。例如，用例层知道实体层，但实体层不应知道用例层。

项目架构实现

本项目对经典清洁架构进行了适当调整，各层对应关系如下：

| 架构层 | 项目对应层 | 实现文件 | |------------------|------------------|------------------| | 外部接口层 | 表现层与驱动层 | middleware.go/handler.go | | 控制器层 | 业务逻辑层 | service.go | | 用例层 | 数据访问层 | repository.go | | 实体层 | 实体定义层 | domain.go |

请求处理流程：

1. 请求首先到达handler.go/middleware.go
2. 调用service.go中的业务逻辑
3. service.go调用符合domain.go定义的repository.go
4. 结果通过handler.go返回给用户

功能模块划分

项目内部采用功能模块化组织：

• internal/auth：认证管理模块
• internal/city：城市管理模块(受保护端点)
• internal/infrastructure：基础设施管理(数据库、框架等)
• internal/misc：杂项端点模块
• internal/user：用户管理模块(公开端点)

API功能详解

1. 杂项端点

• GET /api/v1：服务健康检查

2. 用户管理端点

• GET /api/v1/users：获取所有用户
• POST /api/v1/users：创建新用户
• GET /api/v1/users/<userID>：获取特定用户
• PUT /api/v1/users/<userID>：更新用户信息
• DELETE /api/v1/users/<userID>：删除用户

3. 认证端点

• POST /api/v1/auth/login：用户登录(返回JWT令牌)
• POST /api/v1/auth/logout：用户登出(清除JWT)
• GET /api/v1/auth/private：访问受保护路由(测试JWT有效性)

4. 城市管理端点(需认证)

• GET /api/v1/cities：获取所有城市
• POST /api/v1/cities：创建新城市
• GET /api/v1/cities/<cityID>：获取特定城市
• PUT /api/v1/cities/<cityID>：更新城市信息
• DELETE /api/v1/cities/<cityID>：删除城市

项目部署指南

1. 获取项目代码

git clone <项目仓库地址>
cd <项目路径>/docker-mariadb-clean-arch

2. 启动服务

make start

此命令将：

• 构建Docker镜像
• 启动MariaDB容器
• 自动执行数据库迁移脚本
• 启动API服务

3. 测试API

使用Postman测试(访问localhost:8080)或运行自动化测试：

make test

注意：由于MariaDB的自增ID特性，第二次运行测试前需先执行：

make stop
make start

4. 停止服务

make stop

此命令将：

• 停止并移除容器
• 删除Docker卷
• 清理创建的镜像

常见问题解答

Q：这是实现清洁架构的正确方式吗？

A：清洁架构有多种实现方式，本项目只是其中一种示例。实际项目中应根据需求选择最适合的实现。

Q：为什么认证被视为实现细节？

A：认证不直接与业务用例或数据访问层交互，它可以作为中间件应用于任何路由。这是一种设计选择。

Q：这是推荐的Fiber项目结构吗？

A：对于简单项目，建议从单个main.go开始。随着复杂度增加，再按功能职责拆分。清洁架构适合较复杂的项目。

Q：这个架构只能用于Fiber吗？

A：不是。只需调整handler.go和middleware.go即可适配其他框架(如Gin、Echo等)。数据库层也可类似替换。

Q：这个项目可以用于生产环境吗？

A：项目已尽量考虑生产环境需求，但仍建议根据实际场景进行适当调整和增强。

可能的改进方向

1. 增强测试覆盖：添加更多单元测试和mock测试
2. 扩展API功能：增加更多业务端点
3. 引入缓存：在仓储层添加Redis支持
4. 事务支持：完善数据库事务处理
5. 对象存储：集成S3/MinIO等存储方案
6. 结构调整：单独分离domain定义

技术要点总结

通过本项目，我们可以学习到：

1. 如何在Go中实现清洁架构的分层设计
2. Docker与MariaDB在Go项目中的实践应用
3. JWT认证在清洁架构中的合理位置
4. 1对多关系型数据的处理方式
5. 使用Makefile简化项目管理和自动化流程

这种架构设计使得各层职责清晰，便于维护和扩展，是构建中大型Go项目的良好起点。

recipes 📁 Examples for 🚀 Fiber 项目地址: https://gitcode.com/gh_mirrors/rec/recipes