如何基于请求的tenant_id动态设置Spring JPA Entity的表名？

方法一：利用Hibernate拦截器动态替换表名 #

这是适配多租户分表场景最通用的方案，通过拦截Hibernate生成的SQL，动态替换表名占位符为对应租户的实际表名。

1. 自定义SQL拦截器 #

创建拦截器类，通过ThreadLocal存储当前请求的租户ID，在SQL执行前完成表名替换：

public class TenantTableInterceptor extends EmptyInterceptor {
    private static final ThreadLocal<String> CURRENT_TENANT_ID = new ThreadLocal<>();

    public static void setCurrentTenantId(String tenantId) {
        CURRENT_TENANT_ID.set(tenantId);
    }

    public static void clearCurrentTenantId() {
        CURRENT_TENANT_ID.remove();
    }

    @Override
    public String onPrepareStatement(String sql) {
        String tenantId = CURRENT_TENANT_ID.get();
        if (tenantId != null && sql.contains("table_name_placeholder")) {
            return sql.replace("table_name_placeholder", "table_name_" + tenantId);
        }
        return super.onPrepareStatement(sql);
    }
}

2. 配置实体类 #

实体类中表名使用统一占位符：

@Entity
@Table(name = "table_name_placeholder")
public class YourEntity {
    @Id
    private Long id;
    // 其他与表结构匹配的字段定义
}

3. 注册拦截器到Hibernate #

在Spring配置中把拦截器注入Hibernate：

@Configuration
public class HibernateConfig {
    @Bean
    public HibernatePropertiesCustomizer hibernatePropertiesCustomizer() {
        return properties -> properties.put("hibernate.session_factory.interceptor", new TenantTableInterceptor());
    }
}

4. 从请求中获取并设置租户ID #

用Spring MVC拦截器在请求进入时提取租户ID，请求结束后清理线程变量：

@Component
public class TenantRequestInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        // 从请求头、路径参数或其他位置获取租户ID
        String tenantId = request.getHeader("X-Tenant-Id");
        TenantTableInterceptor.setCurrentTenantId(tenantId);
        return true;
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) throws Exception {
        TenantTableInterceptor.clearCurrentTenantId();
    }
}

注册该拦截器：

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private TenantRequestInterceptor tenantInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(tenantInterceptor).addPathPatterns("/**");
    }
}

完成以上配置后，使用JPA Repository执行查询时，Hibernate会自动将占位符替换为对应租户的表名。

方法二：自定义Repository实现，手动构建动态查询 #

如果不想依赖Hibernate拦截器，可以自定义Repository实现类，根据租户ID手动拼接SQL语句。

1. 定义Repository接口 #

public interface YourEntityRepository extends JpaRepository<YourEntity, Long>, YourEntityCustomRepository {
}

// 自定义查询方法接口
public interface YourEntityCustomRepository {
    List<YourEntity> findByFieldForTenant(String tenantId, String fieldValue);
}

2. 实现自定义Repository逻辑 #

通过EntityManager手动构建原生SQL，指定对应租户的表名：

public class YourEntityCustomRepositoryImpl implements YourEntityCustomRepository {
    @PersistenceContext
    private EntityManager entityManager;

    @Override
    public List<YourEntity> findByFieldForTenant(String tenantId, String fieldValue) {
        String tableName = "table_name_" + tenantId;
        String sql = "SELECT * FROM " + tableName + " WHERE field_name = ?";
        return entityManager.createNativeQuery(sql, YourEntity.class)
                .setParameter(1, fieldValue)
                .getResultList();
    }
}

这种方式适合查询场景较少的情况，优点是无需额外拦截器配置，缺点是每个自定义查询都需要手动拼接SQL，代码冗余度较高。

方法三：结合SpEL动态注入表名（原生SQL场景） #

利用Spring的SpEL表达式，在@Query注解中动态获取当前租户ID，直接生成对应表名的SQL。

1. 定义租户上下文类 #

public class TenantContext {
    private static final ThreadLocal<String> CURRENT_TENANT_ID = new ThreadLocal<>();

    public static void setCurrentTenantId(String tenantId) {
        CURRENT_TENANT_ID.set(tenantId);
    }

    public static String getCurrentTenantId() {
        return CURRENT_TENANT_ID.get();
    }

    public static void clear() {
        CURRENT_TENANT_ID.remove();
    }
}

2. 在Repository中使用SpEL #

注意仅支持原生SQL查询（JPQL面向实体，不支持动态表名）：

public interface YourEntityRepository extends JpaRepository<YourEntity, Long> {
    @Query(value = "SELECT * FROM table_name_#{T(com.yourpackage.TenantContext).getCurrentTenantId()} WHERE id = ?1", nativeQuery = true)
    YourEntity findByIdForTenant(Long id);
}

同样需要在请求拦截器中设置TenantContext的租户ID，确保SpEL能获取到正确值。

注意事项 #

• 所有租户表的Schema必须完全一致，否则实体映射会出现字段不匹配的错误
• 必须使用ThreadLocal存储租户ID，避免多线程请求之间的租户信息混淆
• 请求结束后务必清理ThreadLocal中的值，防止内存泄漏
• 拦截器方案性能损耗极小，适合大部分场景；自定义Repository方案更灵活，但需注意SQL拼接的安全性

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