aalsanie/codes 来源：https://github.com/aalsanie/codes

代码库

适用于 Java 17+。零运行时依赖。 Maven Central (https://central.sonatype.com/artifact/io.github.aalsanie/codes) 持续集成 (https://github.com/aalsanie/codes/actions/workflows/ci.yml) 许可协议

Codes 为 JVM 应用提供稳定的应用结果标识和显式的边界映射。应用保留自己的领域结果或错误模型，并在系统多个部分需要就结果含义达成一致，且不希望将该含义与 HTTP、gRPC、序列化或特定框架耦合时，使用 Codes。领域结果可以在跨边界时保持相同的标识：

文本 com.example.payments:PAYMENT_DECLINED
| +-- HTTP 422
+-- gRPC FAILED_PRECONDITION
+-- 日志/指标 保持 PAYMENT_DECLINED

安装

Gradle:

dependencies {
    implementation("io.github.aalsanie:codes:0.3.1")
}

Maven:

<dependency>
    <groupId>io.github.aalsanie</groupId>
    <artifactId>codes</artifactId>
    <version>0.3.1</version>
</dependency>

适用于 Java 17+。零运行时依赖。 Kotlin 应用通过 JSpecify 空值安全元数据使用相同的 Java API。

自定义结果

OutcomeDefinition paymentDeclined = OutcomeDefinition.custom(
    "com.example.payments",
    "PAYMENT_DECLINED",
    OutcomeState.FAILED,
    "The payment was declined."
);
Outcome outcome = Outcome.of(paymentDeclined);

HttpOutcomeMapper http = HttpOutcomeMapper.standard()
    .withMapping(paymentDeclined, HttpStatusCode.of(422));

GrpcOutcomeMapper grpc = GrpcOutcomeMapper.standard()
    .withMapping(paymentDeclined, GrpcStatusCode.FAILED_PRECONDITION);

OutcomeCode 是稳定的机器标识。协议映射不会改变该标识。

标准结果

文本
OK
INVALID_ARGUMENT
UNAUTHENTICATED
PERMISSION_DENIED
NOT_FOUND
ALREADY_EXISTS
FAILED_PRECONDITION
OUT_OF_RANGE
RATE_LIMITED
CANCELLED
DEADLINE_EXCEEDED
ABORTED
UNIMPLEMENTED
UNAVAILABLE
INTERNAL
DATA_LOSS
RESOURCE_EXHAUSTED

OK 是标准的成功结果。当标准目录不匹配操作时，应用会定义特定于领域的成功、待处理和失败结果。

运行时发生实例

Outcome outcome = Outcome.of(
    StandardOutcomes.NOT_FOUND,
    "customerId=123"
);
System.out.println(outcome.getCode());
System.out.println(outcome.getMessage());
System.out.println(outcome.getDetail());

message 来自可复用的定义。detail 属于单个发生实例。

结构化问题

ValidationResult validation = ValidationResult.invalid(
    Issue.at("email", "Invalid email address.")
);
Outcome outcome = validation.toOutcome(StandardOutcomes.INVALID_ARGUMENT);

ValidationResult 是一个用于聚合问题的小型便利工具。它并非旨在取代应用的结果、验证或函数式编程模型。

HTTP

HttpStatusCode status = HttpOutcomeMapper.standard()
    .map(StandardOutcomes.NOT_FOUND)
    .orNull();
assert status == HttpStatusCode.NOT_FOUND;

某些标准结果在 HTTP 映射中被有意留空，因为正确的状态码取决于具体应用。

gRPC

GrpcStatusCode status = GrpcOutcomeMapper.standard()
    .map(StandardOutcomes.NOT_FOUND)
    .orNull();
assert status == GrpcStatusCode.NOT_FOUND;

标准 gRPC 映射器覆盖所有标准结果。

Kotlin

Java 的 getter 和静态工厂可直接作为 Kotlin 的属性和函数调用：

val outcome = Outcome.of(StandardOutcomes.NOT_FOUND, "customerId=123")
val status = HttpOutcomeMapper.standard().map(outcome).orNull()
check(outcome.code == StandardOutcomes.NOT_FOUND.code)
check(status?.value == 404)

参考资料

• 语义契约
• HTTP 和 gRPC 映射
• 兼容性策略

许可协议

Apache 许可证 2.0 版。