Contract API dùng chung

govex-cloud-api là tầng contract dùng chung của hệ sinh thái Govex Cloud: format response chuẩn, exception tầng service, annotation sinh truy vấn cho JPA/Elasticsearch, annotation phục vụ code generation và validation. Thêm dependency khi service của bạn cần trả kết quả theo chuẩn chung hoặc khai báo DTO tìm kiếm bằng annotation.

Khi nào sử dụng

• Trả response theo format thống nhất bằng ResultMessage (thành công/thất bại, mã lỗi, dữ liệu).
• Ném lỗi nghiệp vụ chuẩn bằng ServiceException / BadParamsException với ResultCode của hệ thống hoặc tự định nghĩa.
• Viết DTO tìm kiếm cho JPA/Elasticsearch bằng annotation (@Like, @Equals, @In, @Between, @Match, @Nested...) thay vì viết tay Specification/query.
• Đánh dấu field nhạy cảm (@Sensitive) hoặc dùng constraint validation dùng chung (@Phone, @GeoCoordinate, @EnumValue).
• Phân nhóm validation theo ngữ cảnh insert/edit/view bằng Insertable, Editable, Viewable.
• Sinh converter cho enum tại compile-time bằng @EnumJpaConverter / @StringToEnumConverter (kết hợp govex-cloud-apt).

Cài đặt

Thêm dependency (không khai version — version do BOM quản lý, xem Cài đặt):

<dependency>
    <groupId>vn.govex.cloud</groupId>
    <artifactId>govex-cloud-api</artifactId>
</dependency>

Hầu hết các dependency khác của Govex Cloud đã phụ thuộc sẵn dependency này, nên nhiều trường hợp bạn không cần khai báo trực tiếp.

Cấu hình

Ý nghĩa của từng annotation/interface do ứng dụng sử dụng quyết định:

Property	Mô tả	Mặc định
jakarta.persistence-api	Cần có trên classpath nếu dùng annotation truy vấn JPA (@Like, @Join...)	do ứng dụng khai báo
elasticsearch-java	Cần có trên classpath nếu dùng annotation truy vấn Elasticsearch (@Match, @Nested...)	do ứng dụng khai báo

Annotation truy vấn JPA được govex-cloud-data-jpa đọc qua Specifications.ofBean(...); annotation truy vấn Elasticsearch được govex-cloud-data-elasticsearch đọc qua EsQueries.

Sử dụng

Response và lỗi

@RestController
@RequestMapping("/api/v1/users")
public class UserController {

    @GetMapping("/{id}")
    public ResultMessage<UserVO> get(@PathVariable String id) {
        return ResultMessage.success(userService.get(id));
    }

    @PostMapping
    public ResultMessage<UserVO> create(@Validated(Insertable.class) @RequestBody UserDTO dto) {
        return ResultMessage.success(userService.create(dto));
    }
}

Trả lỗi với mã hệ thống hoặc mã tự định nghĩa:

return ResultMessage.error(CommonResultCodes.NOT_FOUND);
return ResultMessage.error("CUSTOM_CODE", "Mô tả lỗi");

throw new ServiceException(CommonResultCodes.BAD_REQUEST, "tham số không hợp lệ");
throw new BadParamsException(CommonResultCodes.BAD_REQUEST);

DTO tìm kiếm bằng annotation

@Data
public class UserSearchParam {

    @Like
    private String name;

    @In
    private List<String> status;

    @Between
    private BetweenValue<LocalDate> createdAt;
}

Validation theo ngữ cảnh

public class UserDTO {

    @NotNull(groups = Editable.class)
    private Long id;

    @NotBlank(groups = {Insertable.class, Editable.class})
    private String name;
}

Sinh converter enum (kèm govex-cloud-apt)

@EnumJpaConverter(list = true)
@StringToEnumConverter
public enum Status implements CodeEnum<Integer> {
    ACTIVE(1, "Hoạt động"),
    INACTIVE(0, "Không hoạt động");
    // code, name, constructor, getCode(), getName()...
}

Lưu ý

• Dependency không phụ thuộc Spring Boot; chỉ dùng spring-core cho tiện ích annotation, nên có thể dùng ở cả module -api thuần.
• jakarta.persistence-api và elasticsearch-java được khai báo provided: ứng dụng muốn dùng nhóm annotation tương ứng phải tự thêm thư viện nền.
• @Sensitive/SensitiveType chỉ là metadata đánh dấu; logic che dấu dữ liệu nằm ở govex-cloud-core.
• @Phone, @GeoCoordinate, @EnumValue không mang validator implementation; ứng dụng phải cung cấp validator tương ứng.
• @EnumJpaConverter/@StringToEnumConverter chỉ có tác dụng khi govex-cloud-apt nằm trong annotationProcessorPaths của maven-compiler-plugin — xem govex-cloud-apt.