deepdata/backend/shared/README-zh.md

共享库

概述

共享库包含所有后端服务共用的代码和工具，包括领域构建块、异常处理、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

统一的业务异常处理机制：

// 抛出业务异常
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

错误码枚举接口：

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

所有实体的基类，包含审计字段：

@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 生成和验证：

// 生成 Token
String token = JwtUtil.generateToken(userId, secret, expiration);

// 验证 Token
Claims claims = JwtUtil.validateToken(token, secret);
String userId = claims.getSubject();

使用

在服务中使用共享库

Maven 依赖

<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

@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));
    }
}

快速开始

构建共享库

cd backend
mvn clean install

在服务中使用

共享库会自动被所有后端服务继承。

文档

• AGENTS.md

相关链接

• 后端 README