feat(websocket): integrate WebSocket support and refactor SSE handling
- Added WebSocket support by introducing a new WSHandler and related infrastructure. - Replaced SSE implementations with WebSocket equivalents across message and QR code handlers. - Updated service and repository layers to utilize WebSocket for real-time messaging. - Removed obsolete SSE hub and related code, streamlining the application for WebSocket usage. - Enhanced router to include WebSocket endpoints for real-time communication.
This commit is contained in:
lafay
353
ARCHITECTURE.md
Normal file
353
ARCHITECTURE.md
Normal file
@@ -0,0 +1,353 @@
|
||||
# 后端架构设计规范
|
||||
|
||||
## 1. 分层架构原则
|
||||
|
||||
### 层级定义
|
||||
```
|
||||
Handler (控制器层) → Service (业务逻辑层) → Repository (数据访问层) → Infrastructure (基础设施层)
|
||||
```
|
||||
|
||||
### 层级职责
|
||||
|
||||
| 层级 | 职责 | 依赖关系 |
|
||||
|------|------|----------|
|
||||
| Handler | 接收HTTP请求、参数校验、调用Service、返回响应 | 仅依赖Service |
|
||||
| Service | 实现业务逻辑、事务管理、组合多个Repository | 仅依赖Repository接口 |
|
||||
| Repository | 数据CRUD操作、数据库事务管理 | 仅依赖Model和GORM |
|
||||
| Infrastructure | 缓存、消息队列、RPC等外部服务 | 被Service调用 |
|
||||
|
||||
### 关键约束
|
||||
- **Handler禁止直接依赖Repository或直接操作数据库**
|
||||
- **Service禁止直接依赖`gorm.DB`，必须通过Repository间接操作**
|
||||
- **所有外部依赖通过接口抽象**
|
||||
|
||||
---
|
||||
|
||||
## 2. Repository 层规范
|
||||
|
||||
### 2.1 接口 + 私有实现模式
|
||||
|
||||
所有Repository必须采用接口定义 + 私有实现结构体的模式：
|
||||
|
||||
```go
|
||||
// ✅ 正确：接口 + 私有实现
|
||||
type UserRepository interface {
|
||||
Create(user *model.User) error
|
||||
GetByID(id string) (*model.User, error)
|
||||
}
|
||||
|
||||
type userRepository struct {
|
||||
db *gorm.DB
|
||||
}
|
||||
|
||||
func NewUserRepository(db *gorm.DB) UserRepository {
|
||||
return &userRepository{db: db}
|
||||
}
|
||||
|
||||
func (r *userRepository) Create(user *model.User) error {
|
||||
return r.db.Create(user).Error
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// ❌ 错误：直接暴露结构体指针
|
||||
type UserRepository struct {
|
||||
db *gorm.DB
|
||||
}
|
||||
|
||||
func NewUserRepository(db *gorm.DB) *UserRepository {
|
||||
return &UserRepository{db: db}
|
||||
}
|
||||
```
|
||||
|
||||
### 2.2 Repository方法设计原则
|
||||
|
||||
- 方法签名中**使用接口类型而非指针**：`func (r *userRepository) GetByID(...) (*model.User, error)`
|
||||
- **避免在Repository层直接返回指针切片**，使用值切片更安全
|
||||
- **事务操作在Repository内部封装**，Service不应直接调用`db.Transaction()`
|
||||
|
||||
### 2.3 新增Repository流程
|
||||
|
||||
1. 在`repository/`目录下创建`xxx_repo.go`文件
|
||||
2. 定义`XxxRepository`接口，包含所有数据访问方法
|
||||
3. 创建私有实现结构体`xxxRepository`
|
||||
4. 创建构造函数`NewXxxRepository(db *gorm.DB) XxxRepository`
|
||||
5. 在`wire/repository.go`的`RepositorySet`中注册
|
||||
|
||||
---
|
||||
|
||||
## 3. Service 层规范
|
||||
|
||||
### 3.1 接口 + 私有实现模式
|
||||
|
||||
```go
|
||||
// ✅ 正确
|
||||
type UserService interface {
|
||||
CreateUser(ctx context.Context, req *dto.CreateUserRequest) (*model.User, error)
|
||||
GetUserByID(ctx context.Context, id string) (*model.User, error)
|
||||
}
|
||||
|
||||
type userService struct {
|
||||
userRepo repository.UserRepository
|
||||
// 其他Repo都使用接口类型
|
||||
}
|
||||
|
||||
func NewUserService(userRepo repository.UserRepository) UserService {
|
||||
return &userService{userRepo: userRepo}
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Service依赖管理
|
||||
|
||||
- **所有Repository依赖必须使用接口类型**，禁止使用`*repository.XxxRepository`指针
|
||||
- **禁止在Service中直接持有`gorm.DB`**，如有数据库操作必须下沉到Repository
|
||||
- **如需事务支持**，在Repository中封装事务方法，Service调用封装好的方法
|
||||
|
||||
### 3.3 Service间依赖
|
||||
|
||||
- Service之间通过接口依赖，避免循环依赖
|
||||
- 如Service A需要调用Service B的方法，确保该方法在接口中定义
|
||||
|
||||
---
|
||||
|
||||
## 4. Handler 层规范
|
||||
|
||||
### 4.1 Handler只依赖Service
|
||||
|
||||
```go
|
||||
// ✅ 正确
|
||||
type UserHandler struct {
|
||||
userService service.UserService // 仅依赖Service接口
|
||||
}
|
||||
|
||||
func NewUserHandler(userService service.UserService) *UserHandler {
|
||||
return &UserHandler{userService: userService}
|
||||
}
|
||||
```
|
||||
|
||||
```go
|
||||
// ❌ 错误：直接依赖Repository或Cache
|
||||
type UserHandler struct {
|
||||
userRepo *repository.UserRepository // 禁止
|
||||
cache cache.Cache // 禁止
|
||||
}
|
||||
```
|
||||
|
||||
### 4.2 参数和类型分离
|
||||
|
||||
- **Query参数和Filter类型**应定义在`dto/`包中，而非`repository/`包
|
||||
- Handler负责将HTTP参数转换为DTO后传递给Service
|
||||
|
||||
---
|
||||
|
||||
## 5. DTO/Filter 类型规范
|
||||
|
||||
### 5.1 放置位置
|
||||
|
||||
- **所有查询参数、过滤条件、分页参数**定义在`internal/dto/`目录下
|
||||
- **禁止在`repository/`包中定义供Handler使用的Filter类型**
|
||||
|
||||
### 5.2 文件组织
|
||||
|
||||
```
|
||||
internal/dto/
|
||||
├── filter.go # 通用过滤条件（LogFilter, LoginFilter等）
|
||||
├── user_converter.go # 用户相关转换
|
||||
└── ...
|
||||
```
|
||||
|
||||
### 5.3 Filter类型定义示例
|
||||
|
||||
```go
|
||||
// internal/dto/filter.go
|
||||
|
||||
type LogFilter struct {
|
||||
UserID string
|
||||
Operation string
|
||||
TargetType string
|
||||
StartTime string
|
||||
EndTime string
|
||||
}
|
||||
|
||||
type PaginationParams struct {
|
||||
Page int
|
||||
PageSize int
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Wire 依赖注入规范
|
||||
|
||||
### 6.1 Provider函数设计
|
||||
|
||||
```go
|
||||
// ✅ 正确：Provider返回接口类型
|
||||
func ProvideUserService(
|
||||
userRepo repository.UserRepository, // 接口类型
|
||||
cacheBackend cache.Cache,
|
||||
) service.UserService {
|
||||
return service.NewUserService(userRepo, cacheBackend)
|
||||
}
|
||||
|
||||
// ❌ 错误：返回指针类型
|
||||
func ProvideUserService(userRepo *repository.UserRepository) *service.UserService
|
||||
```
|
||||
|
||||
### 6.2 NewXxxService构造函数签名
|
||||
|
||||
- **构造函数参数使用接口类型**
|
||||
- **返回值使用接口类型**
|
||||
|
||||
```go
|
||||
// ✅ 正确
|
||||
func NewUserService(
|
||||
userRepo repository.UserRepository, // 接口
|
||||
cache cache.Cache,
|
||||
) UserService { // 返回接口
|
||||
return &userService{userRepo: userRepo}
|
||||
}
|
||||
```
|
||||
|
||||
### 6.3 禁止的直接注入
|
||||
|
||||
- **禁止在Handler的Provider中直接注入Repository和Cache**，应仅注入Service
|
||||
- **禁止在Service的Provider中直接注入`gorm.DB`**
|
||||
|
||||
---
|
||||
|
||||
## 7. 事务管理规范
|
||||
|
||||
### 7.1 事务边界在Repository层
|
||||
|
||||
```go
|
||||
// ✅ 正确：事务封装在Repository内部
|
||||
func (r *userRepository) CreateUserWithProfile(user *model.User, profile *model.Profile) error {
|
||||
return r.db.Transaction(func(tx *gorm.DB) error {
|
||||
if err := tx.Create(user).Error; err != nil {
|
||||
return err
|
||||
}
|
||||
profile.UserID = user.ID
|
||||
return tx.Create(profile).Error
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
### 7.2 Service调用事务方法
|
||||
|
||||
```go
|
||||
// ✅ Service通过调用Repository的封装方法使用事务
|
||||
func (s *userService) CreateUser(ctx context.Context, req *dto.CreateUserRequest) error {
|
||||
user := &model.User{Name: req.Name}
|
||||
profile := &model.Profile{Bio: req.Bio}
|
||||
return s.userRepo.CreateUserWithProfile(user, profile)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 常见错误示例
|
||||
|
||||
### 错误1：Handler直接依赖Repository
|
||||
|
||||
```go
|
||||
// ❌ 错误
|
||||
type PostHandler struct {
|
||||
postRepo *repository.PostRepository
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
type PostHandler struct {
|
||||
postService service.PostService
|
||||
}
|
||||
```
|
||||
|
||||
### 错误2：Service直接使用gorm.DB
|
||||
|
||||
```go
|
||||
// ❌ 错误
|
||||
type postService struct {
|
||||
db *gorm.DB
|
||||
}
|
||||
|
||||
func (s *postService) CreatePost(post *model.Post) error {
|
||||
return s.db.Create(post).Error
|
||||
}
|
||||
|
||||
// ✅ 正确：使用Repository
|
||||
func (s *postService) CreatePost(post *model.Post) error {
|
||||
return s.postRepo.Create(post)
|
||||
}
|
||||
```
|
||||
|
||||
### 错误3：Repository返回指针类型
|
||||
|
||||
```go
|
||||
// ❌ 错误
|
||||
func NewUserRepository(db *gorm.DB) *UserRepository {
|
||||
return &UserRepository{db: db}
|
||||
}
|
||||
|
||||
// ✅ 正确
|
||||
func NewUserRepository(db *gorm.DB) UserRepository {
|
||||
return &userRepository{db: db}
|
||||
}
|
||||
```
|
||||
|
||||
### 错误4：Filter类型放在repository包
|
||||
|
||||
```go
|
||||
// ❌ 错误：repository包不应该被handler直接引用
|
||||
package repository
|
||||
type LogFilter struct {
|
||||
UserID string
|
||||
}
|
||||
|
||||
// ✅ 正确：放在dto包
|
||||
package dto
|
||||
type LogFilter struct {
|
||||
UserID string
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 新功能开发 Checklist
|
||||
|
||||
开发新功能时，确保满足以下规范：
|
||||
|
||||
- [ ] **Repository定义**
|
||||
- [ ] 接口 + 私有实现结构体
|
||||
- [ ] 构造函数返回接口类型
|
||||
- [ ] 方法参数使用值类型而非指针
|
||||
- [ ] 在`wire/repository.go`中注册
|
||||
|
||||
- [ ] **Service定义**
|
||||
- [ ] 接口 + 私有实现结构体
|
||||
- [ ] 所有Repository依赖使用接口类型
|
||||
- [ ] 不直接持有`gorm.DB`
|
||||
- [ ] 事务操作下沉到Repository
|
||||
|
||||
- [ ] **Handler定义**
|
||||
- [ ] 仅依赖Service接口
|
||||
- [ ] 不直接依赖Repository或Cache
|
||||
- [ ] Query/Filter参数使用dto包类型
|
||||
|
||||
- [ ] **Wire Provider**
|
||||
- [ ] 参数使用接口类型
|
||||
- [ ] 返回值使用接口类型
|
||||
- [ ] 不直接注入`gorm.DB`到Service
|
||||
|
||||
---
|
||||
|
||||
## 10. 相关文件位置参考
|
||||
|
||||
| 类别 | 目录 |
|
||||
|------|------|
|
||||
| Handler | `internal/handler/` |
|
||||
| Service | `internal/service/` |
|
||||
| Repository | `internal/repository/` |
|
||||
| DTO/Filter | `internal/dto/` |
|
||||
| Model | `internal/model/` |
|
||||
| Wire | `internal/wire/` |
|
||||
| Cache | `internal/cache/` |
|
||||
Reference in New Issue
Block a user