基于clientId实现Thymeleaf JSON模板动态选择及默认回退

核心需求回顾 #

根据请求的clientId加载对应JSON模板，无匹配时自动 fallback 到默认模板；新增客户端仅需添加模板文件，无需修改业务代码。

两种结构方案对比 #

1. 文件名后缀区分（扁平结构）

• 结构示例：

  templates/
  ├── default.json
  ├── clientA.json
  └── clientB.json
  

• 优势：目录结构简单，文件查找直观，Thymeleaf配置成本低
• 劣势：客户端数量增多时，文件杂乱无章，难以分类维护

2. 目录区分（隔离结构）

• 结构示例：

  templates/
  ├── default/
  │   └── json/
  │       └── response.json
  ├── clientA/
  │   └── json/
  │       └── response.json
  └── clientB/
      └── json/
          └── response.json
  

• 优势：按客户端隔离模板，结构清晰；扩展性强，后续可为每个客户端添加多套关联模板
• 劣势：需配置动态路径解析，比扁平结构多一点配置成本

最优方案选择 #

推荐目录区分结构——无论是从长期扩展性还是维护成本来看，这种结构都更适合客户端数量可能增长的场景。若客户端数量极少（3个以内），扁平结构也可临时使用，但目录结构是更稳妥的长期方案。

Spring + Thymeleaf 具体实现 #

1. 模板目录结构

按上述隔离结构创建目录，确保每个客户端目录下的模板文件名与默认目录一致（如都命名为response.json）。

2. Thymeleaf 配置（Spring Boot）

通过配置双模板解析器实现动态匹配+默认 fallback：

@Configuration
public class ThymeleafConfig {

    @Autowired
    private ApplicationContext applicationContext;

    @Bean
    public SpringResourceTemplateResolver clientTemplateResolver() {
        SpringResourceTemplateResolver resolver = new SpringResourceTemplateResolver();
        resolver.setApplicationContext(applicationContext);
        // 动态路径占位符，对应clientId变量
        resolver.setPrefix("classpath:/templates/{clientId}/json/");
        resolver.setSuffix(".json");
        resolver.setTemplateMode(TemplateMode.JSON);
        resolver.setCharacterEncoding("UTF-8");
        resolver.setCacheable(false); // 开发环境关闭缓存，生产环境建议开启
        resolver.setCheckExistence(true); // 检查模板是否存在，不存在则走下一个解析器
        resolver.setOrder(0); // 优先级高于默认解析器
        return resolver;
    }

    @Bean
    public SpringResourceTemplateResolver defaultTemplateResolver() {
        SpringResourceTemplateResolver resolver = new SpringResourceTemplateResolver();
        resolver.setApplicationContext(applicationContext);
        resolver.setPrefix("classpath:/templates/default/json/");
        resolver.setSuffix(".json");
        resolver.setTemplateMode(TemplateMode.JSON);
        resolver.setCharacterEncoding("UTF-8");
        resolver.setCacheable(false);
        resolver.setOrder(1); // 优先级低于客户端解析器
        return resolver;
    }

    @Bean
    public SpringTemplateEngine templateEngine() {
        SpringTemplateEngine engine = new SpringTemplateEngine();
        engine.addTemplateResolver(clientTemplateResolver());
        engine.addTemplateResolver(defaultTemplateResolver());
        return engine;
    }

    @Bean
    public ThymeleafViewResolver thymeleafViewResolver() {
        ThymeleafViewResolver resolver = new ThymeleafViewResolver();
        resolver.setTemplateEngine(templateEngine());
        resolver.setCharacterEncoding("UTF-8");
        resolver.setViewNames(new String[]{"*.json"});
        return resolver;
    }
}

3. 业务代码实现

从请求中获取clientId，传入模板上下文即可完成动态匹配：

@RestController
@RequestMapping("/api")
public class ResponseController {

    @Autowired
    private TemplateEngine templateEngine;

    @GetMapping("/dynamic-response")
    public String getDynamicResponse(@RequestParam String clientId) {
        Context context = new Context();
        // 将clientId传入上下文，用于匹配模板路径
        context.setVariable("clientId", clientId);
        // 模板名对应目录下的response.json
        return templateEngine.process("response", context);
    }
}

关键注意事项 #

• 所有客户端模板与默认模板必须使用相同的文件名，才能保证统一匹配
• 生产环境务必开启模板缓存（setCacheable(true)），避免重复加载文件影响性能
• 若需更复杂的匹配规则（如clientId带特殊字符），可自定义TemplateResolver的模板解析逻辑

内容的提问来源于stack exchange，提问作者Bernie Lenz