# ubdframe

**Repository Path**: captials-team/ubdframe

## Basic Information

- **Project Name**: ubdframe
- **Description**: 通用业务框架（Universal business design）
以相对通用的业务逻辑适用于日常用到的业务模块，可以此作为基础搭建的框架
- **Primary Language**: Go
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-06
- **Last Updated**: 2025-12-04

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# ubdframe

## 介绍
ubdframe 是一个基于 Go 语言的通用后台开发框架，提供了一整套开箱即用的功能模块，包括用户管理、权限控制、日志记录、定时任务、数据统计、块内容管理等。框架采用模块化设计，结合 Gin 和 gRPC，支持 RESTful API 和 WebSocket 服务，适用于构建高效、可扩展的后端服务。

## 安装教程
1. 确保已安装 Go 环境（建议 Go 1.18+）。
2. 克隆项目：
   ```bash
   git clone https://gitee.com/captials-team/ubdframe
   ```
3. 安装依赖：
   ```bash
   go mod download
   ```

## 使用说明
### 1. 安装 swagger-go（swag）
Swagger 用于生成 API 文档：
```bash
go install github.com/swaggo/swag/cmd/swag@latest
```

### 2. 生成文档（手动）
进入对应的服务目录，执行：
```bash
swag init --parseDependency --parseInternal --generalInfo ./src/apps/adminapp/controllers/http/ctr_admin.go --output ./src/apps/adminapp/docs/
```

### 单独生成 admin-service 的 docs
```bash
cd src/apps/adminapp
go run gen_docs.sh
```

### 3. 生成文档（自动/快速）
所有服务已集成 `gen_docs.sh` 脚本，可直接运行生成文档：
```bash
go run gen_docs.sh
```

### 4. 运行并查看文档
启动服务后，访问：
```
http://localhost:8080/swagger/
```

## 主要功能模块
### AdminApp（管理后台）
- �18n 支持（多语言）
- 权限管理（RBAC）
- 日志记录
- 用户管理
- 组织架构管理

### UserApp（用户服务）
- 用户注册/登录/登出
- 第三方登录（微信、QQ 等）
- 用户信息管理
- 验证码发送/校验

### BlockApp（内容块管理）
- 内容块的增删改查
- 支持文本、图片、代码、链接等类型
- 缓存机制支持快速访问

### IotApp（物联网服务）
- 支持 MQTT 设备连接
- 属性上报、事件处理
- 设备注册与拓扑管理

### JobApp（定时任务）
- 支持 Cron 表达式配置
- 任务执行与监控
- 支持多任务并发执行

### OssApp（对象存储）
- 支持本地、阿里云、七牛、MinIO
- 上传配置管理
- 文件上传处理

### RssApp（信息聚合）
- RSS 内容抓取
- 内容缓存
- 多源管理

### SettingApp（配置中心）
- 支持从 DB 或文件加载配置
- 多键设置与获取
- 缓存支持提高性能

### WebApp（Web 服务）
- 模板渲染支持
- 静态资源代理
- 支持中间件扩展

### WssApp（WebSocket 服务）
- 实时消息处理
- 支持订阅/广播
- 在线用户管理

## 项目结构
- `cmd`：入口文件
- `src/apps`：各业务服务模块（AdminApp、UserApp、BlockApp �
- `src/common`：通用常量、工具函数
- `src/domain`：业务模型、请求/响应结构体
- `src/infrastructure`：基础设施层，包括缓存、数据库、消息队列等
- `src/pkg`：通用组件，如 JWT 鉴权、日志、指标、WebSocket 服务等
- `src/resource`：资源文件，如数据库脚本、区域数据、Swagger UI 等

## API 文档
框架集成 Swagger，支持 REST API 和 gRPC 接口文档生成。

### 示例：生成 AdminApp Swagger 文档
```bash
cd src/apps/adminapp
go run gen_docs.sh
```

文档生成路径：
```
src/apps/adminapp/docs/adminservice_swagger.json
src/apps/adminapp/docs/adminservice_swagger.yaml
```

## 开发与测试
- 单元测试位于各模块的 `_test.go` 文件中
- 使用 `go test` 运行测试
- 支持依赖注入（`dig`）和服务注册

## 贡献
欢迎提交 PR 或 Issue。请遵循开源协议并保持代码风格统一。