Google Guice 輕量級依賴注入框架實戰指南

Google Guice 輕量級依賴注入框架實戰指南

Guice (發音 "juice") 是 Google 開發的輕量級依賴注入框架，以「無 XML、極速啟動、類型安全」著稱。本文系統講解 Guice 核心概念、綁定模式、AOP 整合、模組化最佳實踐與遷移 Spring 經驗。

一、核心優勢與定位

二、快速上手：從 @Inject 到 Module

1. Maven 依賴

<dependency>
  <groupId>com.google.inject</groupId>
  <artifactId>guice</artifactId>
  <version>5.1.0</version>
</dependency>
<!-- JSR-330 標準註解 -->
<dependency>
  <groupId>javax.inject</groupId>
  <artifactId>javax.inject</artifactId>
  <version>1</version>
</dependency>
<!-- AOP 支援 -->
<dependency>
  <groupId>com.google.inject.extensions</groupId>
  <artifactId>guice-assistedinject</artifactId>
  <version>5.1.0</version>
</dependency>

2. 服務介面與實現

public interface UserService {
    User findById(Long id);
    User create(UserDTO dto);
}

public class UserServiceImpl implements UserService {
    private final UserRepository repository;
    private final EmailService emailService;
    
    @Inject // 建構子注入 (推薦：不可變、最終、易測試)
    public UserServiceImpl(UserRepository repository, EmailService emailService) {
        this.repository = repository;
        this.emailService = emailService;
    }
    // ...
}

3. Module 綁定配置

public class ServiceModule extends AbstractModule {
    @Override
    protected void configure() {
        // 1. 基礎綁定：介面 → 實現
        bind(UserService.class).to(UserServiceImpl.class).in(Scopes.SINGLETON);
        
        // 2. 實例綁定：配置物件、第三方客戶端
        bind(OkHttpClient.class).toInstance(buildHttpClient());
        
        // 3. 提供者綁定：複雜構建邏輯
        bind(DataSource.class).toProvider(DataSourceProvider.class).in(Scopes.SINGLETON);
        
        // 4. 註解區分多實現
        bind(PaymentService.class).annotatedWith(Names.named("alipay")).to(AlipayService.class);
        bind(PaymentService.class).annotatedWith(Names.named("wechat")).to(WechatPayService.class);
        
        // 5. 類型字面量綁定泛型
        bind(new TypeLiteral>() {}).toInstance(Collections.emptyList());
        
        // 6. Just-in-time 綁定 (隱式)：有 @Inject 建構子的類無需顯式 bind
    }
    
    private OkHttpClient buildHttpClient() {
        return new OkHttpClient.Builder()
            .connectionPool(new ConnectionPool(50, 5, TimeUnit.MINUTES))
            .build();
    }
}

4. Provider 實現動態提供

public class DataSourceProvider implements Provider {
    @Inject private EnvironmentConfig config; // 注入配置物件
    
    @Override
    public DataSource get() {
        HikariDataSource ds = new HikariDataSource();
        ds.setJdbcUrl(config.getDbUrl());
        ds.setUsername(config.getDbUser());
        ds.setPassword(config.getDbPass());
        ds.setMaximumPoolSize(config.getDbPoolSize());
        return ds;
    }
}

5. 啟動與使用

// 1. 定義攔截器
public class TransactionInterceptor implements MethodInterceptor {
    @Inject private TransactionManager txManager;
    
    @Override
    public Object invoke(MethodInvocation invocation) throws Throwable {
        Transaction tx = txManager.begin();
        try {
            Object result = invocation.proceed();
            txManager.commit(tx);
            return result;
        } catch (Exception e) {
            txManager.rollback(tx);
            throw e;
        }
    }
}

// 2. 綁定攔截器 (匹配註解)
public class AopModule extends AbstractModule {
    @Override
    protected void configure() {
        bindInterceptor(
            Matchers.annotatedWith(Transactional.class), // 類或方法標註
            Matchers.any(),
            new TransactionInterceptor()
        );
    }
}

// 3. 使用
@Transactional
public void transfer(Long from, Long to, BigDecimal amount) { ... }

3. AssistedInject：工廠模式自動化

// 參數化建構子：部分依賴由容器注入，部分由工廠參數提供
public class PaymentProcessor {
    private final PaymentGateway gateway; // 容器注入
    private final String orderId;         // 工廠參數
    private final BigDecimal amount;      // 工廠參數
    
    @AssistedInject
    public PaymentProcessor(PaymentGateway gateway, 
                            @Assisted("orderId") String orderId,
                            @Assisted("amount") BigDecimal amount) {
        this.gateway = gateway;
        this.orderId = orderId;
        this.amount = amount;
    }
}

// 工廠介面 (Guice 自動生成實現)
public interface PaymentProcessorFactory {
    PaymentProcessor create(@Assisted("orderId") String orderId, @Assisted("amount") BigDecimal amount);
}

// Module 綁定
install(new FactoryModuleBuilder()
    .implement(PaymentProcessor.class, PaymentProcessor.class)
    .build(PaymentProcessorFactory.class));

4. Private Modules：封裝內部實現

public class PaymentPrivateModule extends PrivateModule {
    @Override
    protected void configure() {
        // 內部綁定：外部不可見
        bind(PaymentGateway.class).to(InternalGatewayImpl.class);
        bind(PaymentService.class).to(PaymentServiceImpl.class);
        
        // 導出介面：外部可注入
        expose(PaymentService.class);
        expose(PaymentGateway.class); // 可選
    }
}

四、最佳實踐與避坑指南

1. 優先建構子注入：欄位 final、不可變、單元測試無需容器、循環依賴編譯期暴露
2. 模組化拆分：按功能域劃分 Module (ServiceModule, RepositoryModule, ConfigModule)，Install 組合
3. 避免 Service Locator 模式：勿在業務代碼中直接 injector.getInstance()，讓容器管理依賴圖
4. 循環依賴處理：Provider 延遲注入、Setter 注入、重構拆分職責
5. 生產環境禁用 Stage.DEVELOPMENT：Stage.PRODUCTION 禁用某些檢查、優化啟動
6. 整合第三方庫：無 @Inject 建構子的類用 Provider 或 toInstance 綁定

五、Spring 遷移對照表

六、總結

Guice 以「程式碼即配置、類型安全、極速啟動」重新定義了輕量級 DI。雖生態不及 Spring 豐富，但在微服務、CLI、測試、Android、嵌入式等場景極具優勢。掌握 Module 綁定、Provider、AOP、AssistedInject、Private Module 核心機制，即可駕輕就熟構建高內聚、低耦合、易測試的 Java 應用。