Java 灵活架构设计：SPI 机制从入门到接入 LLM 与多数据库实战

// ❌ 硬编码的噩梦——到处都是 OpenAI 的影子
public class ChatService {
    public String chat(String userMessage) {
        // 直接 new 具体实现类，完全无法切换
        OpenAiClient client = new OpenAiClient("sk-xxx");
        return client.complete(userMessage);
    }
}

// ServiceLoader 源码关键片段
public final class ServiceLoader<S> implements Iterable<S> {
    
    // 固定扫描路径——这就是为什么配置文件必须放在这里
    private static final String PREFIX = "META-INF/services/";
    
    public static <S> ServiceLoader<S> load(Class<S> service) {
        // 使用线程上下文类加载器（突破双亲委派限制的关键）
        ClassLoader cl = Thread.currentThread().getContextClassLoader();
        return new ServiceLoader<>(Reflection.getCallerClass(), service, cl);
    }
}

// DriverManager 源码（简化版）
static {
    loadInitialDrivers();
}

private static void loadInitialDrivers() {
    // SPI 自动发现所有 Driver 实现
    ServiceLoader<Driver> loadedDrivers = ServiceLoader.load(Driver.class);
    Iterator<Driver> driversIterator = loadedDrivers.iterator();
    while (driversIterator.hasNext()) {
        driversIterator.next(); // 触发实例化，Driver 在 static 块中自动注册
    }
}

// llm-core/src/main/java/com/example/spi/LlmProvider.java
package com.example.spi;

/**
 * LLM 服务提供商统一接口
 * 所有 LLM 实现必须实现此接口，并提供无参构造函数
 */
public interface LlmProvider {

    /**
     * 返回提供商名称（用于日志、监控）
     * @return 如 "openai"、"claude"、"wenxin"
     */
    String name();

    /**
     * 发送消息并获取回复
     * @param systemPrompt 系统提示词
     * @param userMessage  用户消息
     * @return LLM 的回复文本
     */
    String chat(String systemPrompt, String userMessage);

    /**
     * 检查当前提供商是否可用（API Key 是否配置等）
     * @return true 表示可用
     */
    default boolean isAvailable() {
        return true;
    }
}

// llm-openai/src/main/java/com/example/openai/OpenAiProvider.java
package com.example.openai;

import com.example.spi.LlmProvider;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

/**
 * OpenAI GPT 系列模型接入实现
 * 依赖：无参构造，通过环境变量读取 API Key
 */
public class OpenAiProvider implements LlmProvider {

    // 从环境变量读取，避免硬编码 Key
    private static final String API_KEY = System.getenv("OPENAI_API_KEY");
    private static final String API_URL = "https://api.openai.com/v1/chat/completions";
    private static final String MODEL = "gpt-4o";

    private final HttpClient httpClient;

    // SPI 要求：必须有无参构造函数
    public OpenAiProvider() {
        this.httpClient = HttpClient.newHttpClient();
    }

    @Override
    public String name() {
        return "openai";
    }

    @Override
    public boolean isAvailable() {
        return API_KEY != null && !API_KEY.isEmpty();
    }

    @Override
    public String chat(String systemPrompt, String userMessage) {
        // 构造 OpenAI API 请求体（JSON 格式）
        String requestBody = String.format("""
                {
                  "model": "%s",
                  "messages": [
                    {"role": "system", "content": "%s"},
                    {"role": "user", "content": "%s"}
                  ]
                }
                """, MODEL,
                systemPrompt.replace("\"", "\\\""),
                userMessage.replace("\"", "\\\""));

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(API_URL))
                    .header("Content-Type", "application/json")
                    .header("Authorization", "Bearer " + API_KEY)
                    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                    .build();

            HttpResponse<String> response = httpClient.send(
                    request, HttpResponse.BodyHandlers.ofString());

            // 简单解析：提取 choices[0].message.content
            String body = response.body();
            int start = body.indexOf("\"content\":\"") + 11;
            int end = body.indexOf("\"", start);
            return body.substring(start, end);

        } catch (Exception e) {
            throw new RuntimeException("[OpenAI] 调用失败: " + e.getMessage(), e);
        }
    }
}

// llm-claude/src/main/java/com/example/claude/ClaudeProvider.java
package com.example.claude;

import com.example.spi.LlmProvider;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

/**
 * Anthropic Claude 系列模型接入实现
 */
public class ClaudeProvider implements LlmProvider {

    private static final String API_KEY = System.getenv("ANTHROPIC_API_KEY");
    private static final String API_URL = "https://api.anthropic.com/v1/messages";
    private static final String MODEL = "claude-sonnet-4-6";

    private final HttpClient httpClient;

    public ClaudeProvider() {
        this.httpClient = HttpClient.newHttpClient();
    }

    @Override
    public String name() {
        return "claude";
    }

    @Override
    public boolean isAvailable() {
        return API_KEY != null && !API_KEY.isEmpty();
    }

    @Override
    public String chat(String systemPrompt, String userMessage) {
        // Anthropic API 使用不同的请求格式
        String requestBody = String.format("""
                {
                  "model": "%s",
                  "max_tokens": 1024,
                  "system": "%s",
                  "messages": [
                    {"role": "user", "content": "%s"}
                  ]
                }
                """, MODEL,
                systemPrompt.replace("\"", "\\\""),
                userMessage.replace("\"", "\\\""));

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(API_URL))
                    .header("Content-Type", "application/json")
                    .header("x-api-key", API_KEY)
                    .header("anthropic-version", "2023-06-01")
                    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                    .build();

            HttpResponse<String> response = httpClient.send(
                    request, HttpResponse.BodyHandlers.ofString());

            // 解析 Claude 响应格式
            String body = response.body();
            int start = body.indexOf("\"text\":\"") + 8;
            int end = body.indexOf("\"", start);
            return body.substring(start, end);

        } catch (Exception e) {
            throw new RuntimeException("[Claude] 调用失败: " + e.getMessage(), e);
        }
    }
}

// llm-wenxin/src/main/java/com/example/wenxin/WenXinProvider.java
package com.example.wenxin;

import com.example.spi.LlmProvider;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

/**
 * 百度文心一言大模型接入实现
 */
public class WenXinProvider implements LlmProvider {

    private static final String ACCESS_TOKEN = System.getenv("WENXIN_ACCESS_TOKEN");
    private static final String API_URL =
            "https://aip.baidubce.com/rpc/2.0/ai_custom/v1/wenxinworkshop/chat/completions_pro";

    private final HttpClient httpClient;

    public WenXinProvider() {
        this.httpClient = HttpClient.newHttpClient();
    }

    @Override
    public String name() {
        return "wenxin";
    }

    @Override
    public boolean isAvailable() {
        return ACCESS_TOKEN != null && !ACCESS_TOKEN.isEmpty();
    }

    @Override
    public String chat(String systemPrompt, String userMessage) {
        String requestBody = String.format("""
                {
                  "system": "%s",
                  "messages": [
                    {"role": "user", "content": "%s"}
                  ]
                }
                """, systemPrompt.replace("\"", "\\\""),
                userMessage.replace("\"", "\\\""));

        try {
            HttpRequest request = HttpRequest.newBuilder()
                    .uri(URI.create(API_URL + "?access_token=" + ACCESS_TOKEN))
                    .header("Content-Type", "application/json")
                    .POST(HttpRequest.BodyPublishers.ofString(requestBody))
                    .build();

            HttpResponse<String> response = httpClient.send(
                    request, HttpResponse.BodyHandlers.ofString());

            String body = response.body();
            int start = body.indexOf("\"result\":\"") + 10;
            int end = body.indexOf("\"", start);
            return body.substring(start, end);

        } catch (Exception e) {
            throw new RuntimeException("[文心一言] 调用失败: " + e.getMessage(), e);
        }
    }
}

// llm-app/src/main/java/com/example/app/LlmManager.java
package com.example.app;

import com.example.spi.LlmProvider;
import java.util.*;

/**
 * LLM 管理器：通过 SPI 自动发现并管理所有可用的 LLM 提供商
 */
public class LlmManager {

    // 存储所有可用的提供商，key = name()，value = 实例
    private final Map<String, LlmProvider> providers = new LinkedHashMap<>();

    public LlmManager() {
        // 一行代码：自动发现所有在 classpath 中注册的 LLM 实现
        ServiceLoader<LlmProvider> loader = ServiceLoader.load(LlmProvider.class);

        for (LlmProvider provider : loader) {
            if (provider.isAvailable()) {
                providers.put(provider.name(), provider);
                System.out.println("✅ 已加载 LLM 提供商: " + provider.name());
            } else {
                System.out.println("⚠️  跳过不可用提供商: " + provider.name() + "（未配置 API Key）");
            }
        }
    }

    /**
     * 使用指定提供商发送消息
     * @param providerName 提供商名称，如 "openai"、"claude"
     */
    public String chat(String providerName, String systemPrompt, String userMessage) {
        LlmProvider provider = providers.get(providerName);
        if (provider == null) {
            throw new IllegalArgumentException("未找到提供商: " + providerName
                    + "，可用列表: " + providers.keySet());
        }
        return provider.chat(systemPrompt, userMessage);
    }

    /**
     * 使用第一个可用的提供商（兜底策略）
     */
    public String chatWithFallback(String systemPrompt, String userMessage) {
        return providers.values().stream()
                .findFirst()
                .map(p -> p.chat(systemPrompt, userMessage))
                .orElseThrow(() -> new RuntimeException("没有可用的 LLM 提供商"));
    }

    /** 列出所有已加载的提供商 */
    public Set<String> availableProviders() {
        return Collections.unmodifiableSet(providers.keySet());
    }
}

// llm-app/src/main/java/com/example/app/Main.java
package com.example.app;

public class Main {
    public static void main(String[] args) {
        LlmManager manager = new LlmManager();

        // 输出：✅ 已加载 LLM 提供商: openai
        //        ✅ 已加载 LLM 提供商: claude
        //        ✅ 已加载 LLM 提供商: wenxin

        System.out.println("可用提供商: " + manager.availableProviders());

        // 指定使用 Claude
        String reply = manager.chat("claude",
                "你是一个专业的 Java 架构师",
                "请解释一下 SPI 机制的核心优势");
        System.out.println("Claude 回复: " + reply);

        // 如果 claude 挂了，自动兜底到第一个可用的
        String fallbackReply = manager.chatWithFallback(
                "你是一个助手", "你好");
        System.out.println("兜底回复: " + fallbackReply);
    }
}

// db-core/src/main/java/com/example/db/spi/DatabaseDialect.java
package com.example.db.spi;

/**
 * 数据库方言 SPI 接口
 * 封装各数据库在 SQL 语法上的差异
 */
public interface DatabaseDialect {

    /**
     * 返回数据库类型标识（对应 JDBC URL 中的数据库名）
     * @return 如 "mysql"、"postgresql"、"h2"
     */
    String databaseType();

    /**
     * 生成分页查询 SQL
     * @param baseSql  原始查询 SQL（不含分页）
     * @param offset   起始偏移量
     * @param limit    每页记录数
     * @return 带分页的完整 SQL
     */
    String buildPageSql(String baseSql, int offset, int limit);

    /**
     * 生成 UPSERT（插入或更新）SQL
     * @param tableName  表名
     * @param columns    列名数组
     * @param conflictKey 冲突键列名
     * @return UPSERT SQL 语句
     */
    String buildUpsertSql(String tableName, String[] columns, String conflictKey);

    /**
     * 获取当前时间戳的 SQL 函数
     * @return 如 "NOW()"、"CURRENT_TIMESTAMP"
     */
    default String currentTimestampFunction() {
        return "CURRENT_TIMESTAMP";
    }
}

// db-mysql/src/main/java/com/example/db/mysql/MySqlDialect.java
package com.example.db.mysql;

import com.example.db.spi.DatabaseDialect;

/**
 * MySQL 数据库方言实现
 * 支持 MySQL 5.7+ 和 MySQL 8.x
 */
public class MySqlDialect implements DatabaseDialect {

    @Override
    public String databaseType() {
        return "mysql";
    }

    @Override
    public String buildPageSql(String baseSql, int offset, int limit) {
        // MySQL 使用 LIMIT offset, count 语法
        return baseSql + " LIMIT " + offset + ", " + limit;
    }

    @Override
    public String buildUpsertSql(String tableName, String[] columns, String conflictKey) {
        // MySQL 使用 INSERT ... ON DUPLICATE KEY UPDATE 语法
        StringBuilder sb = new StringBuilder();
        sb.append("INSERT INTO ").append(tableName).append(" (");
        sb.append(String.join(", ", columns));
        sb.append(") VALUES (");
        sb.append("?,".repeat(columns.length - 1)).append("?)");
        sb.append(" ON DUPLICATE KEY UPDATE ");

        // 排除主键，其他字段都参与更新
        for (String col : columns) {
            if (!col.equals(conflictKey)) {
                sb.append(col).append(" = VALUES(").append(col).append("), ");
            }
        }
        // 删除最后的逗号空格
        sb.setLength(sb.length() - 2);
        return sb.toString();
    }

    @Override
    public String currentTimestampFunction() {
        return "NOW()";
    }
}

// db-postgresql/src/main/java/com/example/db/pg/PostgreSqlDialect.java
package com.example.db.pg;

import com.example.db.spi.DatabaseDialect;

/**
 * PostgreSQL 数据库方言实现
 * 支持 PostgreSQL 12+
 */
public class PostgreSqlDialect implements DatabaseDialect {

    @Override
    public String databaseType() {
        return "postgresql";
    }

    @Override
    public String buildPageSql(String baseSql, int offset, int limit) {
        // PostgreSQL 使用标准 SQL 的 LIMIT ... OFFSET 语法
        return baseSql + " LIMIT " + limit + " OFFSET " + offset;
    }

    @Override
    public String buildUpsertSql(String tableName, String[] columns, String conflictKey) {
        // PostgreSQL 使用 INSERT ... ON CONFLICT DO UPDATE 语法（更清晰）
        StringBuilder sb = new StringBuilder();
        sb.append("INSERT INTO ").append(tableName).append(" (");
        sb.append(String.join(", ", columns));
        sb.append(") VALUES (");
        sb.append("?,".repeat(columns.length - 1)).append("?)");
        sb.append(" ON CONFLICT (").append(conflictKey).append(") DO UPDATE SET ");

        for (String col : columns) {
            if (!col.equals(conflictKey)) {
                // PostgreSQL 使用 EXCLUDED 引用冲突时传入的新值
                sb.append(col).append(" = EXCLUDED.").append(col).append(", ");
            }
        }
        sb.setLength(sb.length() - 2);
        return sb.toString();
    }
}

// db-h2/src/main/java/com/example/db/h2/H2Dialect.java
package com.example.db.h2;

import com.example.db.spi.DatabaseDialect;

/**
 * H2 内存数据库方言实现（兼容 MySQL 模式）
 * 主要用于本地开发和单元测试
 */
public class H2Dialect implements DatabaseDialect {

    @Override
    public String databaseType() {
        return "h2";
    }

    @Override
    public String buildPageSql(String baseSql, int offset, int limit) {
        // H2 支持标准 SQL 分页语法
        return baseSql + " LIMIT " + limit + " OFFSET " + offset;
    }

    @Override
    public String buildUpsertSql(String tableName, String[] columns, String conflictKey) {
        // H2 支持 MERGE INTO 语法
        StringBuilder sb = new StringBuilder();
        sb.append("MERGE INTO ").append(tableName).append(" (");
        sb.append(String.join(", ", columns));
        sb.append(") KEY (").append(conflictKey).append(") VALUES (");
        sb.append("?,".repeat(columns.length - 1)).append("?)");
        return sb.toString();
    }
}

// db-app/src/main/java/com/example/db/app/DialectManager.java
package com.example.db.app;

import com.example.db.spi.DatabaseDialect;
import java.util.*;

/**
 * 数据库方言管理器
 * 通过 SPI 加载所有方言实现，根据 JDBC URL 自动选择合适的方言
 */
public class DialectManager {

    private final Map<String, DatabaseDialect> dialectMap = new HashMap<>();

    public DialectManager() {
        // SPI 自动发现所有方言实现
        ServiceLoader<DatabaseDialect> loader = ServiceLoader.load(DatabaseDialect.class);
        for (DatabaseDialect dialect : loader) {
            dialectMap.put(dialect.databaseType().toLowerCase(), dialect);
            System.out.println("🗄️  注册数据库方言: " + dialect.databaseType());
        }
    }

    /**
     * 根据 JDBC URL 自动匹配方言
     * 例如 "jdbc:mysql://..." → MySqlDialect
     *      "jdbc:postgresql://..." → PostgreSqlDialect
     */
    public DatabaseDialect detectDialect(String jdbcUrl) {
        String lowerUrl = jdbcUrl.toLowerCase();
        return dialectMap.entrySet().stream()
                .filter(e -> lowerUrl.contains(e.getKey()))
                .map(Map.Entry::getValue)
                .findFirst()
                .orElseThrow(() -> new RuntimeException(
                        "无法识别的数据库类型，URL: " + jdbcUrl
                        + "，已知方言: " + dialectMap.keySet()));
    }

    /** 按名称获取方言 */
    public DatabaseDialect getDialect(String databaseType) {
        return Optional.ofNullable(dialectMap.get(databaseType.toLowerCase()))
                .orElseThrow(() -> new RuntimeException("未注册方言: " + databaseType));
    }
}

// 业务代码：完全不感知是哪种数据库
public class UserRepository {
    
    private final DatabaseDialect dialect;
    
    public UserRepository(String jdbcUrl) {
        DialectManager manager = new DialectManager();
        // 根据 JDBC URL 自动选择方言，无需任何 if-else
        this.dialect = manager.detectDialect(jdbcUrl);
    }
    
    public String buildUserPageQuery(int page, int size) {
        String baseSql = "SELECT * FROM users ORDER BY created_at DESC";
        int offset = (page - 1) * size;
        // 方言自动处理分页语法差异
        return dialect.buildPageSql(baseSql, offset, size);
    }
}

// Dubbo SPI 接口定义（需要加 @SPI 注解）
@SPI("openai")  // 默认使用 openai 实现
public interface LlmProvider {
    String chat(String systemPrompt, String userMessage);
}

// 配置文件：META-INF/dubbo/com.example.spi.LlmProvider
// openai=com.example.openai.OpenAiProvider
// claude=com.example.claude.ClaudeProvider
// wenxin=com.example.wenxin.WenXinProvider

// 调用方：按名称精准获取
ExtensionLoader<LlmProvider> loader = 
    ExtensionLoader.getExtensionLoader(LlmProvider.class);

// 获取默认实现（@SPI 注解指定的 "openai"）
LlmProvider defaultProvider = loader.getDefaultExtension();

// 按别名获取指定实现
LlmProvider claudeProvider = loader.getExtension("claude");

// ❌ 错误：强制遍历导致所有实现被实例化（即使某些用不到）
ServiceLoader<LlmProvider> loader = ServiceLoader.load(LlmProvider.class);
List<LlmProvider> allProviders = new ArrayList<>();
loader.forEach(allProviders::add);  // 全量实例化，资源浪费

// ✅ 正确：按需获取，或者仅实例化 isAvailable() 的实现
ServiceLoader<LlmProvider> loader = ServiceLoader.load(LlmProvider.class);
for (LlmProvider provider : loader) {
    if (provider.isAvailable()) {  // 先检查可用性
        providers.put(provider.name(), provider);
    }
}

// ❌ 错误：多线程共享同一个 ServiceLoader 实例
public class LlmManager {
    // 危险！ServiceLoader 内部的迭代器不是线程安全的
    private static final ServiceLoader<LlmProvider> SHARED_LOADER =
            ServiceLoader.load(LlmProvider.class);
}

// ✅ 正确方案一：每个线程独立 load（有性能开销）
ServiceLoader<LlmProvider> loader = ServiceLoader.load(LlmProvider.class);

// ✅ 正确方案二：提前加载到线程安全的 Map 中（推荐）
private final ConcurrentHashMap<String, LlmProvider> providers = new ConcurrentHashMap<>();
// 在构造函数中一次性加载，之后只读

// 在接口中增加优先级方法
public interface LlmProvider {
    String name();
    String chat(String systemPrompt, String userMessage);
    
    /**
     * 优先级，数字越小优先级越高
     * 用于多个提供商可用时的选择顺序
     */
    default int priority() {
        return 100;
    }
}

// 加载时按优先级排序
public LlmManager() {
    ServiceLoader<LlmProvider> loader = ServiceLoader.load(LlmProvider.class);
    // 转换为 List 后排序
    List<LlmProvider> providerList = new ArrayList<>();
    loader.forEach(providerList::add);
    
    providerList.stream()
            .filter(LlmProvider::isAvailable)
            .sorted(Comparator.comparingInt(LlmProvider::priority))
            .forEach(p -> providers.put(p.name(), p));
}