Quarkus REST API中如何自动实现驼峰属性转下划线小写命名
Quarkus + MicroProfile OpenAPI 全局驼峰转下划线实现方案
完全不需要在每个实体字段上重复添加@Schema(name = "xxx")注解,存在两种可全局生效的适配路径,可根据实际业务场景选型。
方案一:联动Jackson全局命名策略(最简便)
Quarkus生态中MicroProfile OpenAPI的实现(基于SmallRye OpenAPI)会自动同步Jackson的全局属性命名规则,这一联动机制没有在MicroProfile OpenAPI的独立文档章节单独说明,也是很多开发者找不到对应配置路径的核心原因,无需为OpenAPI单独配置映射逻辑。
- 仅需在项目的
application.properties中添加一行全局配置:
# 全局设置Jackson属性命名策略为SNAKE_CASE,自动将驼峰字段转换为下划线小写格式 quarkus.jackson.property-naming-strategy=SNAKE_CASE
- 配置生效后,系统会自动完成两层同步适配:
- 所有REST接口的JSON序列化结果,自动将驼峰字段(如
firstName)转换为下划线格式(如first_name) - 自动生成的OpenAPI文档中,所有实体Schema的属性名会同步应用该转换规则,无需逐字段加注解
- 所有REST接口的JSON序列化结果,自动将驼峰字段(如
- 规则优先级:字段上显式标注的
@Schema(name=xxx)优先级高于全局配置,特殊字段的自定义命名不会被全局规则覆盖
方案二:自定义OpenAPI过滤器独立适配(不影响实际序列化逻辑)
如果需要保持接口实际返回的JSON为驼峰格式,仅要求OpenAPI文档中的Schema展示下划线格式,可通过自定义OpenAPI过滤器实现全局规则,完全不改动Jackson的序列化行为。
- 实现
OASFilter接口,重写filterSchema方法,遍历所有Schema的属性集合,将驼峰命名的属性名通过字符串工具转换为下划线小写格式 - 为实现类添加
@Provider注解,Quarkus会自动扫描该过滤器并在生成OpenAPI文档时全局应用,无需额外手动注册
踩坑提示
两种方案的作用域有明确差异:方案一同时影响接口实际返回格式和OpenAPI文档展示内容;方案二仅作用于OpenAPI文档生成环节,不会改动真实接口的序列化逻辑,选型时不要混淆。
内容的提问来源于stack exchange,提问作者Sasha Shpota
相关产品推荐
相关产品推荐

