该技能用于在 Opik 后端(apps/opik-backend)中开发时遵循既有 Java 代码规范,涉及 API 设计、数据库操作与服务编写。
架构:采用 Resource → Service → DAO 分层,不可跨层;依赖注入使用 Guice 模块与构造器注入(@Inject);数据库为 MySQL(元数据、事务)与 ClickHouse(分析、追加写)。
命名:Resources、测试、URL、数据库表用复数(TracesResource、TracesResourceTest、/v1/private/traces、traces);DAO 与 Service 用单数(TraceDAO、TraceService)。
Lombok:record/DTO 加 @Builder(toBuilder = true),用 builder 而非构造器;内部 record 用 @NonNull,经 @Valid 校验的请求体 DTO 仅用 Jakarta 注解;服务类用 @RequiredArgsConstructor(onConstructor_ = @Inject);接口方法参数不加校验注解。
注意事项:StringTemplate 用 TemplateUtils.newST 避免内存泄漏;列表访问用 getFirst()/getLast();SQL 用文本块;优先不可变集合。接收列表的查询参数从一开始就用复数名。错误处理用 Jakarta 异常(BadRequestException 等),错误响应复用 io.dropwizard.jersey.errors.ErrorMessage 或 com.comet.opik.api.error.ErrorMessage,不新建错误类。日志值用单引号包裹,禁止记录邮箱、密码、令牌、API 密钥、PII 及数据库凭据。
参考文件:clickhouse.md、mysql.md、testing.md、migrations.md、permissions.md。使用限制与具体平台支持暂未提供。