145 lines
3.3 KiB
Markdown
145 lines
3.3 KiB
Markdown
# 共享库
|
|
|
|
## 概述
|
|
|
|
共享库包含所有后端服务共用的代码和工具，包括领域构建块、异常处理、JWT 工具等。
|
|
|
|
## 架构
|
|
|
|
```
|
|
backend/shared/
|
|
├── domain-common/ # DDD 构建块、异常处理
|
|
│ └── src/main/java/com/deepdata/common/
|
|
│ ├── infrastructure/exception/ # BusinessException, ErrorCode
|
|
│ ├── setting/ # 系统参数、模型配置
|
|
│ └── domain/ # Base entities, repositories
|
|
└── security-common/ # JWT 工具、认证辅助
|
|
└── src/main/java/com/deepdata/security/
|
|
```
|
|
|
|
## 库
|
|
|
|
### 1. domain-common
|
|
|
|
#### BusinessException
|
|
统一的业务异常处理机制：
|
|
|
|
```java
|
|
// 抛出业务异常
|
|
throw BusinessException.of(ErrorCode.DATASET_NOT_FOUND)
|
|
.withDetail("dataset_id", datasetId);
|
|
|
|
// 带上下文的异常
|
|
throw BusinessException.of(ErrorCode.VALIDATION_FAILED)
|
|
.withDetail("field", "email")
|
|
.withDetail("reason", "Invalid format");
|
|
```
|
|
|
|
#### ErrorCode
|
|
错误码枚举接口：
|
|
|
|
```java
|
|
public interface ErrorCode {
|
|
String getCode();
|
|
String getMessage();
|
|
HttpStatus getHttpStatus();
|
|
}
|
|
|
|
// 示例
|
|
public enum CommonErrorCode implements ErrorCode {
|
|
SUCCESS("0000", "Success", HttpStatus.OK),
|
|
DATABASE_NOT_FOUND("4001", "Database not found", HttpStatus.NOT_FOUND);
|
|
}
|
|
```
|
|
|
|
#### BaseEntity
|
|
所有实体的基类，包含审计字段：
|
|
|
|
```java
|
|
@Data
|
|
@EqualsAndHashCode(callSuper = true)
|
|
public class BaseEntity<T> implements Serializable {
|
|
@TableId(type = IdType.ASSIGN_ID)
|
|
private String id;
|
|
|
|
@TableField(fill = FieldFill.INSERT)
|
|
private LocalDateTime createdAt;
|
|
|
|
@TableField(fill = FieldFill.INSERT_UPDATE)
|
|
private LocalDateTime updatedAt;
|
|
|
|
@TableField(fill = FieldFill.INSERT)
|
|
private String createdBy;
|
|
|
|
@TableField(fill = FieldFill.INSERT_UPDATE)
|
|
private String updatedBy;
|
|
}
|
|
```
|
|
|
|
### 2. security-common
|
|
|
|
#### JWT 工具
|
|
JWT Token 生成和验证：
|
|
|
|
```java
|
|
// 生成 Token
|
|
String token = JwtUtil.generateToken(userId, secret, expiration);
|
|
|
|
// 验证 Token
|
|
Claims claims = JwtUtil.validateToken(token, secret);
|
|
String userId = claims.getSubject();
|
|
```
|
|
|
|
## 使用
|
|
|
|
### 在服务中使用共享库
|
|
|
|
#### Maven 依赖
|
|
```xml
|
|
<dependency>
|
|
<groupId>com.deepdata</groupId>
|
|
<artifactId>domain-common</artifactId>
|
|
<version>1.0.0-SNAPSHOT</version>
|
|
</dependency>
|
|
<dependency>
|
|
<groupId>com.deepdata</groupId>
|
|
<artifactId>security-common</artifactId>
|
|
<version>1.0.0-SNAPSHOT</version>
|
|
</dependency>
|
|
```
|
|
|
|
#### 使用 BusinessException
|
|
```java
|
|
@RestController
|
|
@RequiredArgsConstructor
|
|
public class DatasetController {
|
|
|
|
public ResponseEntity<DatasetResponse> getDataset(String id) {
|
|
Dataset dataset = datasetService.findById(id);
|
|
if (dataset == null) {
|
|
throw BusinessException.of(ErrorCode.DATASET_NOT_FOUND);
|
|
}
|
|
return ResponseEntity.ok(DatasetResponse.from(dataset));
|
|
}
|
|
}
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
### 构建共享库
|
|
```bash
|
|
cd backend
|
|
mvn clean install
|
|
```
|
|
|
|
### 在服务中使用
|
|
共享库会自动被所有后端服务继承。
|
|
|
|
## 文档
|
|
|
|
- [AGENTS.md](./AGENTS.md)
|
|
|
|
## 相关链接
|
|
|
|
- [后端 README](../README.md)
|