Testing on Bill.Lin's Notes

Kotlin lateinit 完整實作指南：延遲初始化與企業級開發最佳實踐

Thu, 05 Aug 2021 21:07:54 +0800

Kotlin lateinit 完整實作指南

簡介

在 Kotlin 開發中，lateinit 關鍵字提供了一種延遲初始化屬性的優雅方式，特別適用於依賴注入、Android 開發和 Spring Boot 應用。本文將深入探討 lateinit 的工作原理、使用場景、與 lazy 的比較，以及在企業級開發中的最佳實踐。

lateinit 基本概念

核心特性

lateinit 是 Kotlin 提供的延遲初始化修飾符，允許開發者聲明非空屬性而不需要立即初始化：

class UserService {
    // 延遲初始化，避免空值檢查
    lateinit var userRepository: UserRepository
    lateinit var cacheManager: CacheManager
    
    fun initializeServices() {
        userRepository = UserRepositoryImpl()
        cacheManager = RedisCacheManager()
    }
    
    fun findUser(id: Long): User {
        // 直接使用，無需空值檢查
        return userRepository.findById(id) ?: throw UserNotFoundException(id)
    }
}

語法規則與限制

class PropertyRules {
    // ✅ 正確：var 屬性
    lateinit var validProperty: String
    
    // ❌ 錯誤：lateinit 不能用於 val
    // lateinit val invalidProperty: String // 編譯錯誤
    
    // ❌ 錯誤：原始類型不支援
    // lateinit var invalidInt: Int // 編譯錯誤
    
    // ❌ 錯誤：可空類型不支援
    // lateinit var invalidNullable: String? // 編譯錯誤
    
    // ✅ 正確：自定義類別
    lateinit var database: Database
    
    // ✅ 正確：介面類型
    lateinit var service: ServiceInterface
}

lateinit 詳細機制

內部實現原理

// Kotlin 編譯後的 Java 等效代碼
public class UserService {
    private String name;
    
    public final String getName() {
        String var1 = this.name;
        if (var1 == null) {
            Intrinsics.throwUninitializedPropertyAccessException("name");
        }
        return var1;
    }
    
    public final void setName(String value) {
        Intrinsics.checkNotNullParameter(value, "value");
        this.name = value;
    }
}

初始化檢查機制

class InitializationChecker {
    lateinit var database: Database
    lateinit var config: AppConfig
    
    fun checkInitialization() {
        // 檢查是否已初始化
        if (::database.isInitialized) {
            println("Database is ready")
        } else {
            println("Database not initialized")
        }
        
        // 安全初始化模式
        if (!::config.isInitialized) {
            config = loadDefaultConfig()
        }
    }
    
    fun safeAccess(): String {
        return if (::database.isInitialized) {
            database.getConnectionInfo()
        } else {
            "Database not available"
        }
    }
}

企業級應用場景

1. Spring Boot 依賴注入

@Service
class UserManagementService {
    
    @Autowired
    lateinit var userRepository: UserRepository
    
    @Autowired
    lateinit var emailService: EmailService
    
    @Autowired
    lateinit var auditService: AuditService
    
    @Value("\${app.user.max-login-attempts}")
    lateinit var maxLoginAttempts: String
    
    @PostConstruct
    fun validateDependencies() {
        require(::userRepository.isInitialized) { "UserRepository not injected" }
        require(::emailService.isInitialized) { "EmailService not injected" }
        require(::auditService.isInitialized) { "AuditService not injected" }
        
        logger.info("All dependencies initialized successfully")
    }
    
    fun createUser(userData: UserCreateRequest): User {
        val user = User(
            email = userData.email,
            username = userData.username,
            hashedPassword = hashPassword(userData.password)
        )
        
        val savedUser = userRepository.save(user)
        
        // 發送歡迎郵件
        emailService.sendWelcomeEmail(savedUser)
        
        // 記錄審計日誌
        auditService.logUserCreation(savedUser)
        
        return savedUser
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(UserManagementService::class.java)
    }
}

2. Android 開發中的應用

class MainActivity : AppCompatActivity() {
    
    // View 元件延遲初始化
    lateinit var recyclerView: RecyclerView
    lateinit var adapter: UserAdapter
    lateinit var viewModel: UserViewModel
    
    // 網路元件
    lateinit var apiService: ApiService
    lateinit var networkManager: NetworkManager
    
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        
        initializeViews()
        initializeNetwork()
        initializeViewModel()
        setupObservers()
    }
    
    private fun initializeViews() {
        recyclerView = findViewById(R.id.recyclerView)
        adapter = UserAdapter { user -> onUserClicked(user) }
        recyclerView.adapter = adapter
        recyclerView.layoutManager = LinearLayoutManager(this)
    }
    
    private fun initializeNetwork() {
        apiService = RetrofitBuilder.createApiService()
        networkManager = NetworkManager(this)
    }
    
    private fun initializeViewModel() {
        viewModel = ViewModelProvider(this)[UserViewModel::class.java]
    }
    
    private fun setupObservers() {
        // 確保所有元件都已初始化
        require(::viewModel.isInitialized) { "ViewModel not initialized" }
        require(::adapter.isInitialized) { "Adapter not initialized" }
        
        viewModel.users.observe(this) { users ->
            adapter.submitList(users)
        }
        
        viewModel.loading.observe(this) { isLoading ->
            // 處理載入狀態
        }
    }
    
    private fun onUserClicked(user: User) {
        if (::networkManager.isInitialized && networkManager.isConnected()) {
            // 處理用戶點擊事件
            viewModel.loadUserDetails(user.id)
        } else {
            showNoNetworkError()
        }
    }
}

3. 配置管理系統

@Component
class ConfigurationManager {
    
    @Value("\${database.url}")
    lateinit var databaseUrl: String
    
    @Value("\${database.username}")
    lateinit var databaseUsername: String
    
    @Value("\${redis.host}")
    lateinit var redisHost: String
    
    @Value("\${jwt.secret}")
    lateinit var jwtSecret: String
    
    lateinit var databaseConfig: DatabaseConfig
    lateinit var redisConfig: RedisConfig
    lateinit var securityConfig: SecurityConfig
    
    @PostConstruct
    fun initializeConfigurations() {
        validateRequiredProperties()
        buildConfigurations()
        logConfigurationStatus()
    }
    
    private fun validateRequiredProperties() {
        val errors = mutableListOf<String>()
        
        if (!::databaseUrl.isInitialized || databaseUrl.isBlank()) {
            errors.add("Database URL not configured")
        }
        
        if (!::databaseUsername.isInitialized || databaseUsername.isBlank()) {
            errors.add("Database username not configured")
        }
        
        if (!::redisHost.isInitialized || redisHost.isBlank()) {
            errors.add("Redis host not configured")
        }
        
        if (!::jwtSecret.isInitialized || jwtSecret.isBlank()) {
            errors.add("JWT secret not configured")
        }
        
        if (errors.isNotEmpty()) {
            throw ConfigurationException("Configuration errors: ${errors.joinToString(", ")}")
        }
    }
    
    private fun buildConfigurations() {
        databaseConfig = DatabaseConfig(
            url = databaseUrl,
            username = databaseUsername,
            maxPoolSize = 20,
            connectionTimeout = Duration.ofSeconds(30)
        )
        
        redisConfig = RedisConfig(
            host = redisHost,
            port = 6379,
            timeout = Duration.ofSeconds(10)
        )
        
        securityConfig = SecurityConfig(
            jwtSecret = jwtSecret,
            tokenExpiration = Duration.ofHours(24),
            refreshTokenExpiration = Duration.ofDays(7)
        )
    }
    
    private fun logConfigurationStatus() {
        logger.info("Configuration initialized successfully:")
        logger.info("- Database: ${databaseConfig.url}")
        logger.info("- Redis: ${redisConfig.host}:${redisConfig.port}")
        logger.info("- Security: JWT configured with ${securityConfig.tokenExpiration} expiration")
    }
    
    fun getDatabaseConfig(): DatabaseConfig {
        require(::databaseConfig.isInitialized) { "Database configuration not initialized" }
        return databaseConfig
    }
    
    fun getRedisConfig(): RedisConfig {
        require(::redisConfig.isInitialized) { "Redis configuration not initialized" }
        return redisConfig
    }
    
    fun getSecurityConfig(): SecurityConfig {
        require(::securityConfig.isInitialized) { "Security configuration not initialized" }
        return securityConfig
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ConfigurationManager::class.java)
    }
}

lateinit vs lazy 詳細比較

特性對比表

特性	lateinit	lazy
初始化時機	手動控制	首次訪問時
線程安全	否	是（預設）
可變性	var（可重新賦值）	val（不可變）
初始化檢查	::property.isInitialized	無需檢查
記憶體開銷	低	略高（Lazy包裝）
適用場景	依賴注入、外部初始化	延遲計算、高開銷操作

使用場景比較

class ComparisonExample {
    
    // lateinit：適合依賴注入
    @Autowired
    lateinit var repository: UserRepository
    
    // lazy：適合計算密集型初始化
    private val expensiveResource: DatabaseConnection by lazy {
        createDatabaseConnection() // 僅在首次使用時執行
    }
    
    // lateinit：可重新賦值
    lateinit var currentUser: User
    
    fun switchUser(newUser: User) {
        currentUser = newUser // 可以重新賦值
    }
    
    // lazy：線程安全的單例初始化
    private val singleton: ServiceManager by lazy(LazyThreadSafetyMode.SYNCHRONIZED) {
        ServiceManager.create()
    }
    
    // lateinit：手動控制初始化時機
    lateinit var testDatabase: TestDatabase
    
    @BeforeEach
    fun setupTest() {
        testDatabase = createTestDatabase()
    }
    
    @AfterEach
    fun cleanupTest() {
        if (::testDatabase.isInitialized) {
            testDatabase.cleanup()
        }
    }
}

進階使用模式

1. 條件初始化模式

class ConditionalInitialization {
    lateinit var primaryDatabase: Database
    lateinit var secondaryDatabase: Database
    
    fun initializeDatabases(config: DatabaseConfig) {
        // 主資料庫總是初始化
        primaryDatabase = createDatabase(config.primary)
        
        // 次要資料庫僅在啟用時初始化
        if (config.enableSecondary) {
            secondaryDatabase = createDatabase(config.secondary)
        }
    }
    
    fun executeQuery(query: String): QueryResult {
        val result = primaryDatabase.execute(query)
        
        // 安全地使用次要資料庫
        if (::secondaryDatabase.isInitialized) {
            secondaryDatabase.logQuery(query, result)
        }
        
        return result
    }
}

2. 初始化鏈模式

class InitializationChain {
    lateinit var configService: ConfigService
    lateinit var databaseService: DatabaseService
    lateinit var cacheService: CacheService
    lateinit var businessService: BusinessService
    
    fun initializeAll() {
        initializeConfig()
        initializeDatabase()
        initializeCache()
        initializeBusiness()
        validateInitialization()
    }
    
    private fun initializeConfig() {
        configService = ConfigService()
        logger.info("Config service initialized")
    }
    
    private fun initializeDatabase() {
        require(::configService.isInitialized) { "Config service must be initialized first" }
        databaseService = DatabaseService(configService.getDatabaseConfig())
        logger.info("Database service initialized")
    }
    
    private fun initializeCache() {
        require(::configService.isInitialized) { "Config service must be initialized first" }
        cacheService = CacheService(configService.getCacheConfig())
        logger.info("Cache service initialized")
    }
    
    private fun initializeBusiness() {
        require(::databaseService.isInitialized) { "Database service must be initialized first" }
        require(::cacheService.isInitialized) { "Cache service must be initialized first" }
        
        businessService = BusinessService(databaseService, cacheService)
        logger.info("Business service initialized")
    }
    
    private fun validateInitialization() {
        val errors = mutableListOf<String>()
        
        if (!::configService.isInitialized) errors.add("ConfigService")
        if (!::databaseService.isInitialized) errors.add("DatabaseService")
        if (!::cacheService.isInitialized) errors.add("CacheService")
        if (!::businessService.isInitialized) errors.add("BusinessService")
        
        if (errors.isNotEmpty()) {
            throw InitializationException("未初始化的服務: ${errors.joinToString(", ")}")
        }
        
        logger.info("所有服務初始化完成")
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(InitializationChain::class.java)
    }
}

3. 資源管理模式

class ResourceManager : AutoCloseable {
    lateinit var connectionPool: ConnectionPool
    lateinit var cacheManager: CacheManager
    lateinit var fileManager: FileManager
    
    private val initializedResources = mutableSetOf<String>()
    
    fun initializeConnectionPool(config: ConnectionConfig) {
        connectionPool = ConnectionPool.create(config)
        initializedResources.add("connectionPool")
        logger.info("Connection pool initialized with ${config.maxConnections} connections")
    }
    
    fun initializeCacheManager(config: CacheConfig) {
        cacheManager = CacheManager.create(config)
        initializedResources.add("cacheManager")
        logger.info("Cache manager initialized with ${config.maxSize} max size")
    }
    
    fun initializeFileManager(config: FileConfig) {
        fileManager = FileManager.create(config)
        initializedResources.add("fileManager")
        logger.info("File manager initialized with root: ${config.rootPath}")
    }
    
    fun getResourceStatus(): Map<String, Boolean> {
        return mapOf(
            "connectionPool" to ::connectionPool.isInitialized,
            "cacheManager" to ::cacheManager.isInitialized,
            "fileManager" to ::fileManager.isInitialized
        )
    }
    
    override fun close() {
        logger.info("開始關閉資源管理器")
        
        // 按相反順序關閉資源
        if (::fileManager.isInitialized) {
            try {
                fileManager.close()
                logger.info("File manager closed")
            } catch (e: Exception) {
                logger.error("Error closing file manager", e)
            }
        }
        
        if (::cacheManager.isInitialized) {
            try {
                cacheManager.close()
                logger.info("Cache manager closed")
            } catch (e: Exception) {
                logger.error("Error closing cache manager", e)
            }
        }
        
        if (::connectionPool.isInitialized) {
            try {
                connectionPool.close()
                logger.info("Connection pool closed")
            } catch (e: Exception) {
                logger.error("Error closing connection pool", e)
            }
        }
        
        initializedResources.clear()
        logger.info("資源管理器關閉完成")
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ResourceManager::class.java)
    }
}

測試策略

1. 單元測試模式

class UserServiceTest {
    
    @Mock
    lateinit var userRepository: UserRepository
    
    @Mock
    lateinit var emailService: EmailService
    
    @InjectMocks
    lateinit var userService: UserService
    
    @BeforeEach
    fun setup() {
        MockitoAnnotations.openMocks(this)
        
        // 驗證依賴注入是否成功
        assertTrue(::userRepository.isInitialized, "UserRepository should be initialized")
        assertTrue(::emailService.isInitialized, "EmailService should be initialized")
        assertTrue(::userService.isInitialized, "UserService should be initialized")
    }
    
    @Test
    fun `should create user successfully`() {
        // Given
        val userData = UserCreateRequest(
            email = "test@example.com",
            username = "testuser"
        )
        val expectedUser = User(1L, "test@example.com", "testuser")
        
        `when`(userRepository.save(any())).thenReturn(expectedUser)
        doNothing().`when`(emailService).sendWelcomeEmail(any())
        
        // When
        val result = userService.createUser(userData)
        
        // Then
        assertEquals(expectedUser, result)
        verify(userRepository).save(any())
        verify(emailService).sendWelcomeEmail(expectedUser)
    }
    
    @Test
    fun `should handle uninitialized dependencies gracefully`() {
        // 測試未初始化的情況
        val service = UserService()
        
        assertFalse(service::userRepository.isInitialized)
        assertFalse(service::emailService.isInitialized)
        
        assertThrows<UninitializedPropertyAccessException> {
            service.createUser(UserCreateRequest("test@example.com", "test"))
        }
    }
}

2. 整合測試模式

@SpringBootTest
@TestPropertySource(properties = [
    "spring.datasource.url=jdbc:h2:mem:testdb",
    "spring.jpa.hibernate.ddl-auto=create-drop"
])
class UserServiceIntegrationTest {
    
    @Autowired
    lateinit var userService: UserService
    
    @Autowired
    lateinit var userRepository: UserRepository
    
    @TestConfiguration
    class TestConfig {
        @Bean
        @Primary
        fun mockEmailService(): EmailService = mockk(relaxed = true)
    }
    
    @Test
    fun `should initialize all dependencies in Spring context`() {
        // 驗證 Spring 上下文中的依賴注入
        assertTrue(userService::userRepository.isInitialized)
        assertTrue(userService::emailService.isInitialized)
        
        // 執行實際的業務邏輯測試
        val userData = UserCreateRequest("integration@test.com", "integrationuser")
        val result = userService.createUser(userData)
        
        assertNotNull(result.id)
        assertEquals("integration@test.com", result.email)
        assertEquals("integrationuser", result.username)
        
        // 驗證資料實際儲存
        val savedUser = userRepository.findById(result.id!!)
        assertTrue(savedUser.isPresent)
        assertEquals(result.email, savedUser.get().email)
    }
}

效能優化與最佳實踐

1. 記憶體管理

class MemoryOptimizedService {
    // 大型物件使用 lateinit 延遲初始化
    lateinit var largeDataSet: LargeDataSet
    lateinit var heavyProcessor: HeavyProcessor
    
    // 小型配置物件可以直接初始化
    private val config = ServiceConfig()
    
    fun initializeHeavyResources() {
        if (!::largeDataSet.isInitialized) {
            largeDataSet = LargeDataSet.loadFromDatabase()
            logger.info("Large dataset loaded: ${largeDataSet.size} records")
        }
        
        if (!::heavyProcessor.isInitialized) {
            heavyProcessor = HeavyProcessor(largeDataSet)
            logger.info("Heavy processor initialized")
        }
    }
    
    fun processDataIfReady(input: String): String? {
        return if (::heavyProcessor.isInitialized) {
            heavyProcessor.process(input)
        } else {
            logger.warn("Heavy processor not initialized, skipping processing")
            null
        }
    }
    
    // 清理資源
    fun cleanup() {
        if (::heavyProcessor.isInitialized) {
            heavyProcessor.cleanup()
        }
        
        if (::largeDataSet.isInitialized) {
            largeDataSet.cleanup()
        }
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(MemoryOptimizedService::class.java)
    }
}

2. 線程安全考量

class ThreadSafeService {
    @Volatile
    lateinit var sharedResource: SharedResource
    
    private val initializationLock = ReentrantLock()
    private val condition = initializationLock.newCondition()
    
    fun initializeSharedResource(config: ResourceConfig) {
        initializationLock.withLock {
            if (!::sharedResource.isInitialized) {
                sharedResource = SharedResource.create(config)
                condition.signalAll() // 通知等待的線程
                logger.info("Shared resource initialized")
            }
        }
    }
    
    fun accessSharedResource(): String {
        // 等待初始化完成
        initializationLock.withLock {
            while (!::sharedResource.isInitialized) {
                condition.await(5, TimeUnit.SECONDS)
                if (!::sharedResource.isInitialized) {
                    throw TimeoutException("Shared resource initialization timeout")
                }
            }
        }
        
        return sharedResource.getData()
    }
    
    fun isResourceReady(): Boolean {
        return ::sharedResource.isInitialized
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ThreadSafeService::class.java)
    }
}

常見陷阱與錯誤處理

1. 常見錯誤模式

class CommonMistakes {
    lateinit var service: SomeService
    
    // ❌ 錯誤：在初始化前訪問
    fun badExample1() {
        service.doSomething() // UninitializedPropertyAccessException
    }
    
    // ❌ 錯誤：忘記檢查初始化狀態
    fun badExample2() {
        val result = service.getData() // 可能未初始化
        return result
    }
    
    // ✅ 正確：檢查後訪問
    fun goodExample1() {
        if (::service.isInitialized) {
            service.doSomething()
        } else {
            logger.warn("Service not initialized")
        }
    }
    
    // ✅ 正確：防禦性初始化
    fun goodExample2(): String {
        if (!::service.isInitialized) {
            service = SomeService.createDefault()
        }
        return service.getData()
    }
}

2. 錯誤處理策略

class ErrorHandlingService {
    lateinit var primaryService: PrimaryService
    lateinit var backupService: BackupService
    
    fun processRequest(request: Request): Response {
        return try {
            // 嘗試使用主要服務
            if (::primaryService.isInitialized) {
                primaryService.process(request)
            } else {
                throw ServiceNotInitializedException("Primary service not available")
            }
        } catch (e: ServiceNotInitializedException) {
            logger.warn("Primary service unavailable, falling back to backup", e)
            
            // 備援服務處理
            if (::backupService.isInitialized) {
                backupService.process(request)
            } else {
                throw ServiceUnavailableException("No services available")
            }
        } catch (e: Exception) {
            logger.error("Unexpected error processing request", e)
            throw ProcessingException("Failed to process request", e)
        }
    }
    
    fun healthCheck(): HealthStatus {
        val status = HealthStatus()
        
        status.primaryServiceAvailable = ::primaryService.isInitialized
        status.backupServiceAvailable = ::backupService.isInitialized
        
        status.overallStatus = when {
            status.primaryServiceAvailable -> HealthStatus.Status.HEALTHY
            status.backupServiceAvailable -> HealthStatus.Status.DEGRADED
            else -> HealthStatus.Status.UNHEALTHY
        }
        
        return status
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(ErrorHandlingService::class.java)
    }
}

企業級最佳實踐

1. 初始化驗證框架

@Component
class InitializationValidator {
    
    fun validateObject(obj: Any): ValidationResult {
        val result = ValidationResult()
        val clazz = obj::class
        
        // 使用反射檢查所有 lateinit 屬性
        clazz.memberProperties
            .filterIsInstance<KMutableProperty1<Any, Any>>()
            .filter { it.isLateinit }
            .forEach { property ->
                try {
                    if (!property.isInitialized(obj)) {
                        result.addError("Property '${property.name}' is not initialized")
                    } else {
                        result.addSuccess("Property '${property.name}' is initialized")
                    }
                } catch (e: Exception) {
                    result.addError("Error checking property '${property.name}': ${e.message}")
                }
            }
        
        return result
    }
    
    @EventListener
    fun onApplicationReady(event: ApplicationReadyEvent) {
        logger.info("開始驗證應用程式初始化狀態")
        
        val context = event.applicationContext
        val beanNames = context.beanDefinitionNames
        
        var totalBeans = 0
        var validatedBeans = 0
        var errorCount = 0
        
        beanNames.forEach { beanName ->
            try {
                val bean = context.getBean(beanName)
                totalBeans++
                
                val result = validateObject(bean)
                if (result.hasErrors()) {
                    logger.warn("Bean '$beanName' has initialization issues: ${result.getErrors()}")
                    errorCount += result.getErrorCount()
                } else {
                    validatedBeans++
                }
            } catch (e: Exception) {
                logger.debug("Skipped validation for bean '$beanName': ${e.message}")
            }
        }
        
        logger.info("初始化驗證完成: $validatedBeans/$totalBeans beans validated, $errorCount errors found")
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(InitializationValidator::class.java)
    }
}

data class ValidationResult(
    private val errors: MutableList<String> = mutableListOf(),
    private val successes: MutableList<String> = mutableListOf()
) {
    fun addError(error: String) = errors.add(error)
    fun addSuccess(success: String) = successes.add(success)
    fun hasErrors() = errors.isNotEmpty()
    fun getErrors() = errors.toList()
    fun getSuccesses() = successes.toList()
    fun getErrorCount() = errors.size
}

2. 監控與診斷

@Component
class LateinitMonitor {
    
    private val meterRegistry: MeterRegistry = Metrics.globalRegistry
    private val initializationTimer = Timer.builder("lateinit.initialization.time")
        .description("Time taken to initialize lateinit properties")
        .register(meterRegistry)
    
    fun <T> monitorInitialization(
        propertyName: String,
        initializer: () -> T
    ): T {
        return Timer.Sample.start(meterRegistry).use { sample ->
            try {
                val result = initializer()
                
                // 記錄成功的初始化
                Counter.builder("lateinit.initialization.success")
                    .tag("property", propertyName)
                    .register(meterRegistry)
                    .increment()
                
                sample.stop(initializationTimer.withTag("property", propertyName))
                logger.info("Successfully initialized property: $propertyName")
                
                result
            } catch (e: Exception) {
                // 記錄失敗的初始化
                Counter.builder("lateinit.initialization.failure")
                    .tag("property", propertyName)
                    .tag("error", e.javaClass.simpleName)
                    .register(meterRegistry)
                    .increment()
                
                logger.error("Failed to initialize property: $propertyName", e)
                throw e
            }
        }
    }
    
    @Scheduled(fixedRate = 60000) // 每分鐘檢查一次
    fun reportInitializationStatus() {
        val successCount = meterRegistry.counter("lateinit.initialization.success").count()
        val failureCount = meterRegistry.counter("lateinit.initialization.failure").count()
        val totalCount = successCount + failureCount
        
        if (totalCount > 0) {
            val successRate = (successCount / totalCount) * 100
            logger.info("Lateinit initialization statistics - Success rate: ${"%.2f".format(successRate)}% ($successCount/$totalCount)")
        }
    }
    
    companion object {
        private val logger = LoggerFactory.getLogger(LateinitMonitor::class.java)
    }
}

效能基準測試

初始化效能比較

@BenchmarkMode(Mode.AverageTime)
@OutputTimeUnit(TimeUnit.NANOSECONDS)
@State(Scope.Benchmark)
class LateinitPerformanceBenchmark {
    
    // 測試類別
    class LateinitExample {
        lateinit var service: ExpensiveService
        
        fun initializeService() {
            service = ExpensiveService()
        }
    }
    
    class LazyExample {
        private val service: ExpensiveService by lazy { ExpensiveService() }
        
        fun getService(): ExpensiveService = service
    }
    
    class EagerExample {
        private val service: ExpensiveService = ExpensiveService()
        
        fun getService(): ExpensiveService = service
    }
    
    @Benchmark
    fun lateinitInitialization(): ExpensiveService {
        val example = LateinitExample()
        example.initializeService()
        return example.service
    }
    
    @Benchmark
    fun lazyInitialization(): ExpensiveService {
        val example = LazyExample()
        return example.getService()
    }
    
    @Benchmark
    fun eagerInitialization(): ExpensiveService {
        val example = EagerExample()
        return example.getService()
    }
    
    @Benchmark
    fun lateinitAccessAfterInit(): String {
        val example = LateinitExample()
        example.initializeService()
        return example.service.getData() // 訪問已初始化的屬性
    }
    
    @Benchmark
    fun lazyAccess(): String {
        val example = LazyExample()
        example.getService() // 首次訪問，觸發初始化
        return example.getService().getData() // 再次訪問，使用快取值
    }
}

總結

lateinit 是 Kotlin 中強大的延遲初始化機制，特別適用於：

Spring RestTemplate 完整實戰指南：HTTP 客戶端最佳實踐

Wed, 30 Jun 2021 19:39:44 +0800

注意：RestTemplate 自 Spring 5.0 起已進入 maintenance mode，Spring 官方建議新專案改用 RestClient（Spring 6.1+）或 WebClient（reactive 場景）。本文保留 RestTemplate 用法作為參考，並在最後提供三種 HTTP client 的選擇建議。

概述

RestTemplate 是 Spring Framework 提供的同步 HTTP 客戶端，用於簡化 RESTful Web 服務的調用。雖然在 Spring 5.0 之後被標記為維護模式（推薦使用 WebClient），但在許多現有項目中仍廣泛使用。本文將深入介紹 RestTemplate 的完整使用方法和最佳實踐。

核心特性

簡化 HTTP 操作：提供便捷的 GET、POST、PUT、DELETE 等方法
自動序列化：支援 JSON、XML 等格式的自動轉換
異常處理：統一的異常處理機制
攔截器支援：請求和響應攔截器
靈活配置：連接池、超時、重試等配置

適用場景

微服務通信：服務間的 HTTP 調用
第三方 API 整合：調用外部 REST API
資料同步：不同系統間的資料交換
輕量級 HTTP 客戶端：簡單的 HTTP 請求需求

基礎配置與設定

1. 依賴配置

<dependencies>
    <!-- Spring Boot Starter Web -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-web</artifactId>
    </dependency>
    
    <!-- Apache HttpClient（可選，提供更好的連接池支援） -->
    <dependency>
        <groupId>org.apache.httpcomponents</groupId>
        <artifactId>httpclient</artifactId>
    </dependency>
    
    <!-- OkHttp（可選，現代化的 HTTP 客戶端） -->
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
    </dependency>
    
    <!-- Jackson（JSON 處理） -->
    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
    </dependency>
    
    <!-- Testing -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

2. 基礎配置類

package com.example.resttemplate.config;

import org.apache.http.client.HttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.impl.conn.PoolingHttpClientConnectionManager;
import org.springframework.boot.web.client.RestTemplateBuilder;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.http.client.HttpComponentsClientHttpRequestFactory;
import org.springframework.http.client.SimpleClientHttpRequestFactory;
import org.springframework.http.converter.json.MappingJackson2HttpMessageConverter;
import org.springframework.web.client.RestTemplate;

import java.time.Duration;
import java.util.Arrays;

@Configuration
public class RestTemplateConfig {
    
    /**
     * 基礎 RestTemplate 配置
     */
    @Bean("basicRestTemplate")
    public RestTemplate basicRestTemplate() {
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(5000);  // 連接超時 5 秒
        factory.setReadTimeout(10000);    // 讀取超時 10 秒
        
        RestTemplate restTemplate = new RestTemplate(factory);
        
        // 添加 JSON 消息轉換器
        restTemplate.getMessageConverters().add(new MappingJackson2HttpMessageConverter());
        
        return restTemplate;
    }
    
    /**
     * 使用 RestTemplateBuilder 構建（推薦方式）
     */
    @Bean("standardRestTemplate")
    public RestTemplate standardRestTemplate(RestTemplateBuilder builder) {
        return builder
                .setConnectTimeout(Duration.ofSeconds(5))
                .setReadTimeout(Duration.ofSeconds(10))
                .additionalMessageConverters(new MappingJackson2HttpMessageConverter())
                .build();
    }
    
    /**
     * 高性能 RestTemplate（使用 Apache HttpClient）
     */
    @Bean("highPerformanceRestTemplate")
    public RestTemplate highPerformanceRestTemplate() {
        // 連接池管理器
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(200);          // 最大連接數
        connectionManager.setDefaultMaxPerRoute(50); // 每個路由的最大連接數
        
        // HttpClient 配置
        HttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setConnectionManagerShared(true)
                .build();
        
        // 請求工廠
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient);
        factory.setConnectTimeout(5000);
        factory.setReadTimeout(10000);
        
        return new RestTemplate(factory);
    }
    
    /**
     * 帶有自訂配置的 RestTemplate
     */
    @Bean("customRestTemplate")
    public RestTemplate customRestTemplate() {
        RestTemplate restTemplate = new RestTemplate();
        
        // 添加攔截器
        restTemplate.setInterceptors(Arrays.asList(
                new LoggingInterceptor(),
                new AuthenticationInterceptor(),
                new RetryInterceptor()
        ));
        
        // 設置錯誤處理器
        restTemplate.setErrorHandler(new CustomResponseErrorHandler());
        
        return restTemplate;
    }
}

3. 屬性配置

# application.yml
rest-client:
  connection:
    timeout: 5000
    read-timeout: 10000
    max-connections: 200
    max-connections-per-route: 50
  retry:
    max-attempts: 3
    delay: 1000
  base-urls:
    user-service: "http://localhost:8081"
    order-service: "http://localhost:8082"
    payment-service: "http://localhost:8083"

@ConfigurationProperties(prefix = "rest-client")
@Component
public class RestClientProperties {
    
    private Connection connection = new Connection();
    private Retry retry = new Retry();
    private Map<String, String> baseUrls = new HashMap<>();
    
    // getter 和 setter 方法
    
    public static class Connection {
        private int timeout = 5000;
        private int readTimeout = 10000;
        private int maxConnections = 200;
        private int maxConnectionsPerRoute = 50;
        
        // getter 和 setter 方法
    }
    
    public static class Retry {
        private int maxAttempts = 3;
        private long delay = 1000;
        
        // getter 和 setter 方法
    }
}

基礎 HTTP 操作

1. GET 請求

package com.example.resttemplate.service;

import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.*;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
import org.springframework.web.util.UriComponentsBuilder;

import java.net.URI;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

@Service
public class RestClientService {
    
    private final RestTemplate restTemplate;
    
    public RestClientService(@Qualifier("standardRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    /**
     * 基礎 GET 請求
     */
    public User getUserById(Long userId) {
        String url = "https://api.example.com/users/{id}";
        return restTemplate.getForObject(url, User.class, userId);
    }
    
    /**
     * 帶有查詢參數的 GET 請求
     */
    public List<User> getUsersByDepartment(String department, int page, int size) {
        String url = "https://api.example.com/users";
        
        URI uri = UriComponentsBuilder.fromUriString(url)
                .queryParam("department", department)
                .queryParam("page", page)
                .queryParam("size", size)
                .build()
                .toUri();
        
        ResponseEntity<List<User>> response = restTemplate.exchange(
                uri,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<List<User>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 使用 Map 作為 URI 變數
     */
    public User getUserWithMap(Long userId) {
        String url = "https://api.example.com/users/{id}/profile/{section}";
        
        Map<String, Object> uriVariables = new HashMap<>();
        uriVariables.put("id", userId);
        uriVariables.put("section", "basic");
        
        return restTemplate.getForObject(url, User.class, uriVariables);
    }
    
    /**
     * 帶有請求頭的 GET 請求
     */
    public User getUserWithHeaders(Long userId, String authToken) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + authToken);
        headers.set("Accept", MediaType.APPLICATION_JSON_VALUE);
        
        HttpEntity<String> entity = new HttpEntity<>(headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url,
                HttpMethod.GET,
                entity,
                User.class,
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * 獲取完整的響應資訊
     */
    public ResponseEntity<User> getUserWithFullResponse(Long userId) {
        String url = "https://api.example.com/users/{id}";
        
        ResponseEntity<User> response = restTemplate.getForEntity(url, User.class, userId);
        
        // 可以獲取狀態碼、頭部、主體等資訊
        HttpStatus statusCode = response.getStatusCode();
        HttpHeaders responseHeaders = response.getHeaders();
        User user = response.getBody();
        
        return response;
    }
}

2. POST 請求

/**
 * POST 請求範例
 */
@Service
public class PostRequestService {
    
    private final RestTemplate restTemplate;
    
    public PostRequestService(@Qualifier("standardRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    /**
     * 基礎 POST 請求
     */
    public User createUser(User newUser) {
        String url = "https://api.example.com/users";
        return restTemplate.postForObject(url, newUser, User.class);
    }
    
    /**
     * 帶有請求頭的 POST 請求
     */
    public ResponseEntity<User> createUserWithHeaders(User newUser, String authToken) {
        String url = "https://api.example.com/users";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("Authorization", "Bearer " + authToken);
        
        HttpEntity<User> request = new HttpEntity<>(newUser, headers);
        
        return restTemplate.postForEntity(url, request, User.class);
    }
    
    /**
     * 表單數據 POST 請求
     */
    public String submitForm(String email, String password) {
        String url = "https://api.example.com/login";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_FORM_URLENCODED);
        
        MultiValueMap<String, String> formData = new LinkedMultiValueMap<>();
        formData.add("email", email);
        formData.add("password", password);
        
        HttpEntity<MultiValueMap<String, String>> request = new HttpEntity<>(formData, headers);
        
        return restTemplate.postForObject(url, request, String.class);
    }
    
    /**
     * JSON 數據 POST 請求
     */
    public ApiResponse<User> createUserWithResponse(CreateUserRequest request) {
        String url = "https://api.example.com/users";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("X-Request-ID", generateRequestId());
        
        HttpEntity<CreateUserRequest> httpEntity = new HttpEntity<>(request, headers);
        
        ResponseEntity<ApiResponse<User>> response = restTemplate.exchange(
                url,
                HttpMethod.POST,
                httpEntity,
                new ParameterizedTypeReference<ApiResponse<User>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 文件上傳 POST 請求
     */
    public String uploadFile(MultipartFile file, String description) {
        String url = "https://api.example.com/files/upload";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.MULTIPART_FORM_DATA);
        
        MultiValueMap<String, Object> formData = new LinkedMultiValueMap<>();
        formData.add("file", file.getResource());
        formData.add("description", description);
        
        HttpEntity<MultiValueMap<String, Object>> request = new HttpEntity<>(formData, headers);
        
        return restTemplate.postForObject(url, request, String.class);
    }
    
    private String generateRequestId() {
        return UUID.randomUUID().toString();
    }
}

3. PUT 和 DELETE 請求

/**
 * PUT 和 DELETE 請求範例
 */
@Service
public class UpdateDeleteService {
    
    private final RestTemplate restTemplate;
    
    public UpdateDeleteService(@Qualifier("standardRestTemplate") RestTemplate restTemplate) {
        this.restTemplate = restTemplate;
    }
    
    /**
     * PUT 更新請求
     */
    public User updateUser(Long userId, User updatedUser) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<User> request = new HttpEntity<>(updatedUser, headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url,
                HttpMethod.PUT,
                request,
                User.class,
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * PATCH 部分更新請求
     */
    public User partialUpdateUser(Long userId, Map<String, Object> updates) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<Map<String, Object>> request = new HttpEntity<>(updates, headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url,
                HttpMethod.PATCH,
                request,
                User.class,
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * DELETE 刪除請求
     */
    public void deleteUser(Long userId) {
        String url = "https://api.example.com/users/{id}";
        restTemplate.delete(url, userId);
    }
    
    /**
     * 帶有響應的 DELETE 請求
     */
    public ApiResponse<Void> deleteUserWithResponse(Long userId, String authToken) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + authToken);
        
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        ResponseEntity<ApiResponse<Void>> response = restTemplate.exchange(
                url,
                HttpMethod.DELETE,
                request,
                new ParameterizedTypeReference<ApiResponse<Void>>() {},
                userId
        );
        
        return response.getBody();
    }
    
    /**
     * 批量刪除請求
     */
    public void deleteUsers(List<Long> userIds) {
        String url = "https://api.example.com/users/batch";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        DeleteBatchRequest request = new DeleteBatchRequest(userIds);
        HttpEntity<DeleteBatchRequest> httpEntity = new HttpEntity<>(request, headers);
        
        restTemplate.exchange(
                url,
                HttpMethod.DELETE,
                httpEntity,
                Void.class
        );
    }
}

高級功能與自訂

1. 攔截器實作

/**
 * 日誌攔截器
 */
@Component
public class LoggingInterceptor implements ClientHttpRequestInterceptor {
    
    private static final Logger logger = LoggerFactory.getLogger(LoggingInterceptor.class);
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        logRequest(request, body);
        
        long startTime = System.currentTimeMillis();
        ClientHttpResponse response = execution.execute(request, body);
        long duration = System.currentTimeMillis() - startTime;
        
        logResponse(response, duration);
        
        return response;
    }
    
    private void logRequest(HttpRequest request, byte[] body) {
        logger.info("===========================request begin================================================");
        logger.info("URI         : {}", request.getURI());
        logger.info("Method      : {}", request.getMethod());
        logger.info("Headers     : {}", request.getHeaders());
        logger.info("Request body: {}", new String(body, StandardCharsets.UTF_8));
        logger.info("==========================request end================================================");
    }
    
    private void logResponse(ClientHttpResponse response, long duration) throws IOException {
        logger.info("============================response begin==========================================");
        logger.info("Status code  : {}", response.getStatusCode());
        logger.info("Status text  : {}", response.getStatusText());
        logger.info("Headers      : {}", response.getHeaders());
        logger.info("Duration     : {} ms", duration);
        logger.info("=======================response end=================================================");
    }
}

/**
 * 認證攔截器
 */
@Component
public class AuthenticationInterceptor implements ClientHttpRequestInterceptor {
    
    private final TokenService tokenService;
    
    public AuthenticationInterceptor(TokenService tokenService) {
        this.tokenService = tokenService;
    }
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        // 獲取並設置認證 token
        String token = tokenService.getCurrentToken();
        if (token != null) {
            request.getHeaders().set("Authorization", "Bearer " + token);
        }
        
        return execution.execute(request, body);
    }
}

/**
 * 重試攔截器
 */
@Component
public class RetryInterceptor implements ClientHttpRequestInterceptor {
    
    private static final Logger logger = LoggerFactory.getLogger(RetryInterceptor.class);
    
    private final int maxRetries;
    private final long retryDelay;
    
    public RetryInterceptor(@Value("${rest-client.retry.max-attempts:3}") int maxRetries,
                           @Value("${rest-client.retry.delay:1000}") long retryDelay) {
        this.maxRetries = maxRetries;
        this.retryDelay = retryDelay;
    }
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request,
            byte[] body,
            ClientHttpRequestExecution execution) throws IOException {
        
        IOException lastException = null;
        
        for (int attempt = 1; attempt <= maxRetries; attempt++) {
            try {
                ClientHttpResponse response = execution.execute(request, body);
                
                // 檢查是否需要重試（例如：5xx 錯誤）
                if (shouldRetry(response) && attempt < maxRetries) {
                    logger.warn("Request failed with status {}, retrying... (attempt {}/{})",
                               response.getStatusCode(), attempt, maxRetries);
                    
                    // 等待後重試
                    try {
                        Thread.sleep(retryDelay * attempt); // 指數退避
                    } catch (InterruptedException e) {
                        Thread.currentThread().interrupt();
                        throw new IOException("Interrupted during retry delay", e);
                    }
                    continue;
                }
                
                return response;
                
            } catch (IOException e) {
                lastException = e;
                
                if (attempt < maxRetries) {
                    logger.warn("Request failed, retrying... (attempt {}/{}) - {}", 
                               attempt, maxRetries, e.getMessage());
                    
                    try {
                        Thread.sleep(retryDelay * attempt);
                    } catch (InterruptedException ie) {
                        Thread.currentThread().interrupt();
                        throw new IOException("Interrupted during retry delay", ie);
                    }
                } else {
                    logger.error("Request failed after {} attempts", maxRetries, e);
                }
            }
        }
        
        throw lastException;
    }
    
    private boolean shouldRetry(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        return status.is5xxServerError() || status == HttpStatus.REQUEST_TIMEOUT;
    }
}

2. 自訂錯誤處理器

/**
 * 自訂響應錯誤處理器
 */
@Component
public class CustomResponseErrorHandler implements ResponseErrorHandler {
    
    private static final Logger logger = LoggerFactory.getLogger(CustomResponseErrorHandler.class);
    
    @Override
    public boolean hasError(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        return status.series() == HttpStatus.Series.CLIENT_ERROR ||
               status.series() == HttpStatus.Series.SERVER_ERROR;
    }
    
    @Override
    public void handleError(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        String responseBody = getResponseBody(response);
        
        logger.error("HTTP Error: {} - {}, Response: {}", 
                    status.value(), status.getReasonPhrase(), responseBody);
        
        switch (status.series()) {
            case CLIENT_ERROR:
                handleClientError(status, responseBody);
                break;
            case SERVER_ERROR:
                handleServerError(status, responseBody);
                break;
            default:
                throw new RestClientException("Unknown HTTP error: " + status);
        }
    }
    
    private void handleClientError(HttpStatus status, String responseBody) {
        switch (status) {
            case BAD_REQUEST:
                throw new BadRequestException("Invalid request: " + responseBody);
            case UNAUTHORIZED:
                throw new UnauthorizedException("Authentication required");
            case FORBIDDEN:
                throw new ForbiddenException("Access denied");
            case NOT_FOUND:
                throw new NotFoundException("Resource not found");
            case CONFLICT:
                throw new ConflictException("Resource conflict: " + responseBody);
            case TOO_MANY_REQUESTS:
                throw new RateLimitException("Rate limit exceeded");
            default:
                throw new ClientErrorException("Client error: " + status + " - " + responseBody);
        }
    }
    
    private void handleServerError(HttpStatus status, String responseBody) {
        switch (status) {
            case INTERNAL_SERVER_ERROR:
                throw new ServerErrorException("Internal server error: " + responseBody);
            case BAD_GATEWAY:
                throw new BadGatewayException("Bad gateway");
            case SERVICE_UNAVAILABLE:
                throw new ServiceUnavailableException("Service unavailable");
            case GATEWAY_TIMEOUT:
                throw new GatewayTimeoutException("Gateway timeout");
            default:
                throw new ServerErrorException("Server error: " + status + " - " + responseBody);
        }
    }
    
    private String getResponseBody(ClientHttpResponse response) {
        try (InputStream inputStream = response.getBody()) {
            return StreamUtils.copyToString(inputStream, StandardCharsets.UTF_8);
        } catch (IOException e) {
            logger.warn("Failed to read response body", e);
            return "Unable to read response body";
        }
    }
}

3. 自訂異常類別

// 基礎異常類別
public abstract class RestClientException extends RuntimeException {
    public RestClientException(String message) {
        super(message);
    }
    
    public RestClientException(String message, Throwable cause) {
        super(message, cause);
    }
}

// 客戶端錯誤異常
public class ClientErrorException extends RestClientException {
    public ClientErrorException(String message) {
        super(message);
    }
}

public class BadRequestException extends ClientErrorException {
    public BadRequestException(String message) {
        super(message);
    }
}

public class UnauthorizedException extends ClientErrorException {
    public UnauthorizedException(String message) {
        super(message);
    }
}

public class ForbiddenException extends ClientErrorException {
    public ForbiddenException(String message) {
        super(message);
    }
}

public class NotFoundException extends ClientErrorException {
    public NotFoundException(String message) {
        super(message);
    }
}

public class ConflictException extends ClientErrorException {
    public ConflictException(String message) {
        super(message);
    }
}

public class RateLimitException extends ClientErrorException {
    public RateLimitException(String message) {
        super(message);
    }
}

// 服務器錯誤異常
public class ServerErrorException extends RestClientException {
    public ServerErrorException(String message) {
        super(message);
    }
}

public class BadGatewayException extends ServerErrorException {
    public BadGatewayException(String message) {
        super(message);
    }
}

public class ServiceUnavailableException extends ServerErrorException {
    public ServiceUnavailableException(String message) {
        super(message);
    }
}

public class GatewayTimeoutException extends ServerErrorException {
    public GatewayTimeoutException(String message) {
        super(message);
    }
}

實際應用場景

1. 微服務通信

/**
 * 用戶服務客戶端
 */
@Service
public class UserServiceClient {
    
    private final RestTemplate restTemplate;
    private final RestClientProperties properties;
    
    public UserServiceClient(@Qualifier("highPerformanceRestTemplate") RestTemplate restTemplate,
                            RestClientProperties properties) {
        this.restTemplate = restTemplate;
        this.properties = properties;
    }
    
    /**
     * 獲取用戶資訊
     */
    public Optional<User> getUserById(Long userId) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users/{id}";
        
        try {
            User user = restTemplate.getForObject(url, User.class, userId);
            return Optional.ofNullable(user);
        } catch (NotFoundException e) {
            return Optional.empty();
        }
    }
    
    /**
     * 批量獲取用戶資訊
     */
    public List<User> getUsersByIds(List<Long> userIds) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users/batch";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<List<Long>> request = new HttpEntity<>(userIds, headers);
        
        ResponseEntity<List<User>> response = restTemplate.exchange(
                url,
                HttpMethod.POST,
                request,
                new ParameterizedTypeReference<List<User>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 創建用戶
     */
    public User createUser(CreateUserRequest request) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<CreateUserRequest> httpEntity = new HttpEntity<>(request, headers);
        
        return restTemplate.postForObject(url, httpEntity, User.class);
    }
    
    /**
     * 更新用戶狀態
     */
    public void updateUserStatus(Long userId, UserStatus status) {
        String url = properties.getBaseUrls().get("user-service") + "/api/users/{id}/status";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        UpdateStatusRequest request = new UpdateStatusRequest(status);
        HttpEntity<UpdateStatusRequest> httpEntity = new HttpEntity<>(request, headers);
        
        restTemplate.exchange(url, HttpMethod.PUT, httpEntity, Void.class, userId);
    }
}

/**
 * 訂單服務客戶端
 */
@Service
public class OrderServiceClient {
    
    private final RestTemplate restTemplate;
    private final RestClientProperties properties;
    
    public OrderServiceClient(@Qualifier("highPerformanceRestTemplate") RestTemplate restTemplate,
                             RestClientProperties properties) {
        this.restTemplate = restTemplate;
        this.properties = properties;
    }
    
    /**
     * 創建訂單
     */
    public Order createOrder(CreateOrderRequest request) {
        String url = properties.getBaseUrls().get("order-service") + "/api/orders";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        headers.set("X-Request-ID", UUID.randomUUID().toString());
        
        HttpEntity<CreateOrderRequest> httpEntity = new HttpEntity<>(request, headers);
        
        ResponseEntity<Order> response = restTemplate.postForEntity(url, httpEntity, Order.class);
        
        if (response.getStatusCode() == HttpStatus.CREATED) {
            return response.getBody();
        } else {
            throw new RuntimeException("Failed to create order: " + response.getStatusCode());
        }
    }
    
    /**
     * 獲取用戶訂單列表
     */
    public PagedResponse<Order> getUserOrders(Long userId, int page, int size) {
        String url = properties.getBaseUrls().get("order-service") + "/api/users/{userId}/orders";
        
        URI uri = UriComponentsBuilder.fromUriString(url)
                .queryParam("page", page)
                .queryParam("size", size)
                .build(userId);
        
        ResponseEntity<PagedResponse<Order>> response = restTemplate.exchange(
                uri,
                HttpMethod.GET,
                null,
                new ParameterizedTypeReference<PagedResponse<Order>>() {}
        );
        
        return response.getBody();
    }
    
    /**
     * 取消訂單
     */
    public void cancelOrder(Long orderId, String reason) {
        String url = properties.getBaseUrls().get("order-service") + "/api/orders/{id}/cancel";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        CancelOrderRequest request = new CancelOrderRequest(reason);
        HttpEntity<CancelOrderRequest> httpEntity = new HttpEntity<>(request, headers);
        
        restTemplate.exchange(url, HttpMethod.POST, httpEntity, Void.class, orderId);
    }
}

2. 第三方 API 整合

/**
 * 第三方支付服務整合
 */
@Service
public class PaymentGatewayClient {
    
    private final RestTemplate restTemplate;
    private final PaymentConfig paymentConfig;
    
    public PaymentGatewayClient(@Qualifier("customRestTemplate") RestTemplate restTemplate,
                               PaymentConfig paymentConfig) {
        this.restTemplate = restTemplate;
        this.paymentConfig = paymentConfig;
    }
    
    /**
     * 創建支付訂單
     */
    public PaymentResponse createPayment(PaymentRequest paymentRequest) {
        String url = paymentConfig.getBaseUrl() + "/api/v1/payments";
        
        HttpHeaders headers = createAuthHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<PaymentRequest> request = new HttpEntity<>(paymentRequest, headers);
        
        try {
            ResponseEntity<PaymentResponse> response = restTemplate.postForEntity(
                    url, request, PaymentResponse.class);
            
            return response.getBody();
        } catch (Exception e) {
            throw new PaymentException("Failed to create payment", e);
        }
    }
    
    /**
     * 查詢支付狀態
     */
    public PaymentStatus queryPaymentStatus(String paymentId) {
        String url = paymentConfig.getBaseUrl() + "/api/v1/payments/{paymentId}/status";
        
        HttpHeaders headers = createAuthHeaders();
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        try {
            ResponseEntity<PaymentStatusResponse> response = restTemplate.exchange(
                    url, HttpMethod.GET, request, PaymentStatusResponse.class, paymentId);
            
            return response.getBody().getStatus();
        } catch (NotFoundException e) {
            throw new PaymentNotFoundException("Payment not found: " + paymentId);
        }
    }
    
    /**
     * 退款請求
     */
    public RefundResponse processRefund(String paymentId, RefundRequest refundRequest) {
        String url = paymentConfig.getBaseUrl() + "/api/v1/payments/{paymentId}/refund";
        
        HttpHeaders headers = createAuthHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<RefundRequest> request = new HttpEntity<>(refundRequest, headers);
        
        try {
            ResponseEntity<RefundResponse> response = restTemplate.exchange(
                    url, HttpMethod.POST, request, RefundResponse.class, paymentId);
            
            return response.getBody();
        } catch (Exception e) {
            throw new RefundException("Failed to process refund", e);
        }
    }
    
    /**
     * 創建認證頭
     */
    private HttpHeaders createAuthHeaders() {
        HttpHeaders headers = new HttpHeaders();
        
        String auth = paymentConfig.getApiKey() + ":" + paymentConfig.getApiSecret();
        String encodedAuth = Base64.getEncoder().encodeToString(auth.getBytes());
        
        headers.set("Authorization", "Basic " + encodedAuth);
        headers.set("X-API-Version", paymentConfig.getApiVersion());
        
        return headers;
    }
}

/**
 * 外部資料同步服務
 */
@Service
public class DataSyncService {
    
    private final RestTemplate restTemplate;
    private final DataSyncConfig config;
    
    public DataSyncService(@Qualifier("standardRestTemplate") RestTemplate restTemplate,
                          DataSyncConfig config) {
        this.restTemplate = restTemplate;
        this.config = config;
    }
    
    /**
     * 同步用戶資料
     */
    @Async
    public CompletableFuture<SyncResult> syncUserData() {
        String url = config.getExternalApiUrl() + "/users/export";
        
        HttpHeaders headers = new HttpHeaders();
        headers.set("Authorization", "Bearer " + config.getAccessToken());
        headers.set("Accept", MediaType.APPLICATION_JSON_VALUE);
        
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        try {
            ResponseEntity<List<ExternalUser>> response = restTemplate.exchange(
                    url, 
                    HttpMethod.GET, 
                    request, 
                    new ParameterizedTypeReference<List<ExternalUser>>() {}
            );
            
            List<ExternalUser> externalUsers = response.getBody();
            
            // 處理同步邏輯
            int syncedCount = processSyncData(externalUsers);
            
            return CompletableFuture.completedFuture(
                    new SyncResult(true, syncedCount, "Sync completed successfully"));
            
        } catch (Exception e) {
            return CompletableFuture.completedFuture(
                    new SyncResult(false, 0, "Sync failed: " + e.getMessage()));
        }
    }
    
    private int processSyncData(List<ExternalUser> externalUsers) {
        // 同步處理邏輯
        return externalUsers != null ? externalUsers.size() : 0;
    }
}

效能優化與監控

1. 連接池優化

/**
 * 高效能 RestTemplate 配置
 */
@Configuration
public class HighPerformanceRestTemplateConfig {
    
    @Bean("pooledRestTemplate")
    public RestTemplate pooledRestTemplate() {
        // 連接池管理器配置
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(300);              // 最大連接數
        connectionManager.setDefaultMaxPerRoute(100);    // 每個路由的最大連接數
        connectionManager.setValidateAfterInactivity(2000); // 連接空閒檢查時間
        
        // 連接池清理策略
        connectionManager.closeExpiredConnections();
        connectionManager.closeIdleConnections(30, TimeUnit.SECONDS);
        
        // 請求配置
        RequestConfig requestConfig = RequestConfig.custom()
                .setConnectionRequestTimeout(5000)    // 從連接池獲取連接的超時時間
                .setConnectTimeout(5000)              // 連接超時時間
                .setSocketTimeout(30000)              // 讀取超時時間
                .build();
        
        // HttpClient 配置
        CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setDefaultRequestConfig(requestConfig)
                .setRetryHandler(new DefaultHttpRequestRetryHandler(3, true))
                .setKeepAliveStrategy((response, context) -> 30 * 1000) // 30 秒 keep-alive
                .build();
        
        // 請求工廠
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient);
        
        return new RestTemplate(factory);
    }
    
    /**
     * 連接池監控
     */
    @Component
    public class ConnectionPoolMonitor {
        
        private final PoolingHttpClientConnectionManager connectionManager;
        private final MeterRegistry meterRegistry;
        
        public ConnectionPoolMonitor(PoolingHttpClientConnectionManager connectionManager,
                                   MeterRegistry meterRegistry) {
            this.connectionManager = connectionManager;
            this.meterRegistry = meterRegistry;
            
            // 註冊連接池指標
            Gauge.builder("http.connections.total")
                    .description("Total connections in pool")
                    .register(meterRegistry, this, monitor -> monitor.connectionManager.getTotalStats().getMax());
            
            Gauge.builder("http.connections.available")
                    .description("Available connections in pool")
                    .register(meterRegistry, this, monitor -> monitor.connectionManager.getTotalStats().getAvailable());
            
            Gauge.builder("http.connections.leased")
                    .description("Leased connections in pool")
                    .register(meterRegistry, this, monitor -> monitor.connectionManager.getTotalStats().getLeased());
        }
        
        @EventListener
        @Async
        public void logConnectionPoolStats(ApplicationReadyEvent event) {
            ScheduledExecutorService executor = Executors.newScheduledThreadPool(1);
            executor.scheduleAtFixedRate(this::logStats, 0, 30, TimeUnit.SECONDS);
        }
        
        private void logStats() {
            PoolStats totalStats = connectionManager.getTotalStats();
            logger.info("Connection Pool Stats - Total: {}, Available: {}, Leased: {}, Pending: {}",
                       totalStats.getMax(), totalStats.getAvailable(), 
                       totalStats.getLeased(), totalStats.getPending());
        }
    }
}

2. 響應時間監控

/**
 * HTTP 請求監控攔截器
 */
@Component
public class MetricsInterceptor implements ClientHttpRequestInterceptor {
    
    private final MeterRegistry meterRegistry;
    private final Timer.Builder timerBuilder;
    
    public MetricsInterceptor(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
        this.timerBuilder = Timer.builder("http.client.requests")
                .description("HTTP client request duration");
    }
    
    @Override
    public ClientHttpResponse intercept(
            HttpRequest request, 
            byte[] body, 
            ClientHttpRequestExecution execution) throws IOException {
        
        Timer.Sample sample = Timer.start(meterRegistry);
        
        try {
            ClientHttpResponse response = execution.execute(request, body);
            
            // 記錄成功請求指標
            sample.stop(timerBuilder
                    .tag("method", request.getMethod().name())
                    .tag("uri", getUriTemplate(request.getURI()))
                    .tag("status", String.valueOf(response.getStatusCode().value()))
                    .tag("outcome", getOutcome(response))
                    .register(meterRegistry));
            
            return response;
            
        } catch (IOException e) {
            // 記錄失敗請求指標
            sample.stop(timerBuilder
                    .tag("method", request.getMethod().name())
                    .tag("uri", getUriTemplate(request.getURI()))
                    .tag("status", "IO_ERROR")
                    .tag("outcome", "ERROR")
                    .register(meterRegistry));
            
            throw e;
        }
    }
    
    private String getUriTemplate(URI uri) {
        String path = uri.getPath();
        // 簡化路徑模板（移除具體 ID）
        return path.replaceAll("/\\d+", "/{id}");
    }
    
    private String getOutcome(ClientHttpResponse response) throws IOException {
        HttpStatus status = response.getStatusCode();
        if (status.is2xxSuccessful()) {
            return "SUCCESS";
        } else if (status.is4xxClientError()) {
            return "CLIENT_ERROR";
        } else if (status.is5xxServerError()) {
            return "SERVER_ERROR";
        } else {
            return "UNKNOWN";
        }
    }
}

3. 快取策略

/**
 * 帶快取的 REST 客戶端
 */
@Service
public class CachedRestClientService {
    
    private final RestTemplate restTemplate;
    private final CacheManager cacheManager;
    
    public CachedRestClientService(@Qualifier("standardRestTemplate") RestTemplate restTemplate,
                                  CacheManager cacheManager) {
        this.restTemplate = restTemplate;
        this.cacheManager = cacheManager;
    }
    
    /**
     * 帶快取的用戶查詢
     */
    @Cacheable(value = "users", key = "#userId", unless = "#result == null")
    public User getUserById(Long userId) {
        String url = "https://api.example.com/users/{id}";
        return restTemplate.getForObject(url, User.class, userId);
    }
    
    /**
     * 快取失效更新
     */
    @CacheEvict(value = "users", key = "#userId")
    public User updateUser(Long userId, User updatedUser) {
        String url = "https://api.example.com/users/{id}";
        
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        
        HttpEntity<User> request = new HttpEntity<>(updatedUser, headers);
        
        ResponseEntity<User> response = restTemplate.exchange(
                url, HttpMethod.PUT, request, User.class, userId);
        
        return response.getBody();
    }
    
    /**
     * 條件快取：基於響應頭的快取策略
     */
    public User getUserWithConditionalCache(Long userId) {
        String url = "https://api.example.com/users/{id}";
        
        // 檢查快取
        Cache cache = cacheManager.getCache("users");
        Cache.ValueWrapper cachedValue = cache.get(userId);
        
        HttpHeaders headers = new HttpHeaders();
        
        if (cachedValue != null) {
            CachedUser cachedUser = (CachedUser) cachedValue.get();
            // 添加 If-None-Match 頭
            headers.set("If-None-Match", cachedUser.getEtag());
        }
        
        HttpEntity<String> request = new HttpEntity<>(headers);
        
        try {
            ResponseEntity<User> response = restTemplate.exchange(
                    url, HttpMethod.GET, request, User.class, userId);
            
            // 更新快取
            String etag = response.getHeaders().getETag();
            if (etag != null) {
                CachedUser cachedUser = new CachedUser(response.getBody(), etag);
                cache.put(userId, cachedUser);
            }
            
            return response.getBody();
            
        } catch (HttpClientErrorException e) {
            if (e.getStatusCode() == HttpStatus.NOT_MODIFIED && cachedValue != null) {
                // 返回快取的值
                return ((CachedUser) cachedValue.get()).getUser();
            }
            throw e;
        }
    }
    
    private static class CachedUser {
        private final User user;
        private final String etag;
        
        public CachedUser(User user, String etag) {
            this.user = user;
            this.etag = etag;
        }
        
        public User getUser() { return user; }
        public String getEtag() { return etag; }
    }
}

測試策略

1. 單元測試

/**
 * RestTemplate 單元測試
 */
@ExtendWith(MockitoExtension.class)
class RestClientServiceTest {
    
    @Mock
    private RestTemplate restTemplate;
    
    @InjectMocks
    private RestClientService restClientService;
    
    private MockRestServiceServer mockServer;
    private ObjectMapper objectMapper;
    
    @BeforeEach
    void setUp() {
        mockServer = MockRestServiceServer.createServer(restTemplate);
        objectMapper = new ObjectMapper();
    }
    
    @Test
    @DisplayName("成功獲取用戶資訊")
    void testGetUserById_Success() throws JsonProcessingException {
        // Given
        Long userId = 1L;
        User expectedUser = new User(userId, "john@example.com", "John", "Doe");
        String expectedJson = objectMapper.writeValueAsString(expectedUser);
        
        mockServer.expect(requestTo("https://api.example.com/users/1"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withSuccess(expectedJson, MediaType.APPLICATION_JSON));
        
        // When
        User actualUser = restClientService.getUserById(userId);
        
        // Then
        mockServer.verify();
        assertThat(actualUser).isNotNull();
        assertThat(actualUser.getId()).isEqualTo(userId);
        assertThat(actualUser.getEmail()).isEqualTo("john@example.com");
    }
    
    @Test
    @DisplayName("用戶不存在時拋出異常")
    void testGetUserById_NotFound() {
        // Given
        Long userId = 999L;
        
        mockServer.expect(requestTo("https://api.example.com/users/999"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withStatus(HttpStatus.NOT_FOUND));
        
        // When & Then
        assertThatThrownBy(() -> restClientService.getUserById(userId))
                .isInstanceOf(NotFoundException.class);
        
        mockServer.verify();
    }
    
    @Test
    @DisplayName("帶有查詢參數的 GET 請求")
    void testGetUsersByDepartment() throws JsonProcessingException {
        // Given
        String department = "IT";
        int page = 0;
        int size = 10;
        List<User> expectedUsers = Arrays.asList(
                new User(1L, "john@example.com", "John", "Doe"),
                new User(2L, "jane@example.com", "Jane", "Smith")
        );
        String expectedJson = objectMapper.writeValueAsString(expectedUsers);
        
        mockServer.expect(requestTo(containsString("https://api.example.com/users")))
                  .andExpect(queryParam("department", "IT"))
                  .andExpect(queryParam("page", "0"))
                  .andExpect(queryParam("size", "10"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withSuccess(expectedJson, MediaType.APPLICATION_JSON));
        
        // When
        List<User> actualUsers = restClientService.getUsersByDepartment(department, page, size);
        
        // Then
        mockServer.verify();
        assertThat(actualUsers).hasSize(2);
    }
    
    @Test
    @DisplayName("POST 請求創建用戶")
    void testCreateUser() throws JsonProcessingException {
        // Given
        User newUser = new User(null, "bob@example.com", "Bob", "Johnson");
        User createdUser = new User(3L, "bob@example.com", "Bob", "Johnson");
        String requestJson = objectMapper.writeValueAsString(newUser);
        String responseJson = objectMapper.writeValueAsString(createdUser);
        
        mockServer.expect(requestTo("https://api.example.com/users"))
                  .andExpect(method(HttpMethod.POST))
                  .andExpect(content().json(requestJson))
                  .andExpected(header("Content-Type", "application/json"))
                  .andRespond(withSuccess(responseJson, MediaType.APPLICATION_JSON));
        
        // When
        User actualUser = restClientService.createUser(newUser);
        
        // Then
        mockServer.verify();
        assertThat(actualUser.getId()).isEqualTo(3L);
        assertThat(actualUser.getEmail()).isEqualTo("bob@example.com");
    }
    
    @Test
    @DisplayName("服務器錯誤時的重試機制")
    void testRetryOnServerError() {
        // Given
        Long userId = 1L;
        
        mockServer.expect(times(3), requestTo("https://api.example.com/users/1"))
                  .andExpect(method(HttpMethod.GET))
                  .andRespond(withServerError());
        
        // When & Then
        assertThatThrownBy(() -> restClientService.getUserById(userId))
                .isInstanceOf(ServerErrorException.class);
        
        mockServer.verify();
    }
}

2. 整合測試

/**
 * RestTemplate 整合測試
 */
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
@TestPropertySource(locations = "classpath:application-integration-test.properties")
class RestClientIntegrationTest {
    
    @Autowired
    private RestClientService restClientService;
    
    @Autowired
    private TestRestTemplate testRestTemplate;
    
    @MockBean
    private RestTemplate restTemplate;
    
    private WireMockServer wireMockServer;
    
    @BeforeEach
    void setUp() {
        wireMockServer = new WireMockServer(wireMockConfig().port(8089));
        wireMockServer.start();
        configureFor("localhost", 8089);
    }
    
    @AfterEach
    void tearDown() {
        wireMockServer.stop();
    }
    
    @Test
    @DisplayName("完整的用戶管理流程")
    void testCompleteUserManagementFlow() throws JsonProcessingException {
        ObjectMapper objectMapper = new ObjectMapper();
        
        // 1. 模擬創建用戶 API
        User newUser = new User(null, "integration@example.com", "Integration", "Test");
        User createdUser = new User(1L, "integration@example.com", "Integration", "Test");
        
        stubFor(post(urlEqualTo("/api/users"))
                .willReturn(aResponse()
                        .withStatus(201)
                        .withHeader("Content-Type", "application/json")
                        .withBody(objectMapper.writeValueAsString(createdUser))));
        
        // 2. 模擬獲取用戶 API
        stubFor(get(urlEqualTo("/api/users/1"))
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody(objectMapper.writeValueAsString(createdUser))));
        
        // 3. 模擬更新用戶 API
        User updatedUser = new User(1L, "updated@example.com", "Updated", "User");
        stubFor(put(urlEqualTo("/api/users/1"))
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody(objectMapper.writeValueAsString(updatedUser))));
        
        // 4. 模擬刪除用戶 API
        stubFor(delete(urlEqualTo("/api/users/1"))
                .willReturn(aResponse().withStatus(204)));
        
        // 執行測試流程
        // 創建用戶
        User created = restClientService.createUser(newUser);
        assertThat(created.getId()).isEqualTo(1L);
        
        // 獲取用戶
        User retrieved = restClientService.getUserById(1L);
        assertThat(retrieved.getEmail()).isEqualTo("integration@example.com");
        
        // 更新用戶
        User updated = restClientService.updateUser(1L, updatedUser);
        assertThat(updated.getEmail()).isEqualTo("updated@example.com");
        
        // 刪除用戶
        assertDoesNotThrow(() -> restClientService.deleteUser(1L));
        
        // 驗證所有請求都被調用
        verify(postRequestedFor(urlEqualTo("/api/users")));
        verify(getRequestedFor(urlEqualTo("/api/users/1")));
        verify(putRequestedFor(urlEqualTo("/api/users/1")));
        verify(deleteRequestedFor(urlEqualTo("/api/users/1")));
    }
    
    @Test
    @DisplayName("錯誤處理和重試機制")
    void testErrorHandlingAndRetry() {
        // 模擬服務器錯誤，然後成功
        stubFor(get(urlEqualTo("/api/users/1"))
                .inScenario("Retry Scenario")
                .whenScenarioStateIs(STARTED)
                .willSetStateTo("First Attempt")
                .willReturn(aResponse().withStatus(500)));
        
        stubFor(get(urlEqualTo("/api/users/1"))
                .inScenario("Retry Scenario")
                .whenScenarioStateIs("First Attempt")
                .willSetStateTo("Second Attempt")
                .willReturn(aResponse().withStatus(500)));
        
        stubFor(get(urlEqualTo("/api/users/1"))
                .inScenario("Retry Scenario")
                .whenScenarioStateIs("Second Attempt")
                .willReturn(aResponse()
                        .withStatus(200)
                        .withHeader("Content-Type", "application/json")
                        .withBody("{\"id\":1,\"email\":\"test@example.com\"}")));
        
        // 執行測試
        User user = restClientService.getUserById(1L);
        assertThat(user.getId()).isEqualTo(1L);
        
        // 驗證重試了 3 次
        verify(3, getRequestedFor(urlEqualTo("/api/users/1")));
    }
}

現代化替代方案

1. WebClient 遷移指南

/**
 * WebClient 遷移範例
 */
@Service
public class ModernRestClientService {
    
    private final WebClient webClient;
    
    public ModernRestClientService(WebClient.Builder webClientBuilder) {
        this.webClient = webClientBuilder
                .baseUrl("https://api.example.com")
                .defaultHeader(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_JSON_VALUE)
                .build();
    }
    
    /**
     * 異步 GET 請求
     */
    public Mono<User> getUserByIdAsync(Long userId) {
        return webClient.get()
                .uri("/users/{id}", userId)
                .retrieve()
                .bodyToMono(User.class);
    }
    
    /**
     * 響應式 POST 請求
     */
    public Mono<User> createUserAsync(User newUser) {
        return webClient.post()
                .uri("/users")
                .bodyValue(newUser)
                .retrieve()
                .bodyToMono(User.class);
    }
    
    /**
     * 錯誤處理
     */
    public Mono<User> getUserWithErrorHandling(Long userId) {
        return webClient.get()
                .uri("/users/{id}", userId)
                .retrieve()
                .onStatus(HttpStatus::is4xxClientError, 
                         response -> Mono.error(new NotFoundException("User not found")))
                .onStatus(HttpStatus::is5xxServerError,
                         response -> Mono.error(new ServerErrorException("Server error")))
                .bodyToMono(User.class);
    }
    
    /**
     * 流式處理
     */
    public Flux<User> getAllUsersStream() {
        return webClient.get()
                .uri("/users/stream")
                .retrieve()
                .bodyToFlux(User.class);
    }
}

2. RestTemplate vs WebClient 對比

特性	RestTemplate	WebClient
API 風格	同步阻塞	異步非阻塞
響應式支援	不支援	完整支援
效能	中等	高
記憶體使用	較高	較低
背壓處理	不支援	支援
Spring 5+ 支援	維護模式	主推方案
學習曲線	較低	較高

最佳實踐與建議

1. 配置最佳實踐

/**
 * RestTemplate 最佳實踐配置
 */
@Configuration
public class RestTemplateBestPractices {
    
    /**
     * 生產環境推薦配置
     */
    @Bean
    @Primary
    public RestTemplate productionRestTemplate() {
        // 1. 使用連接池
        PoolingHttpClientConnectionManager connectionManager = new PoolingHttpClientConnectionManager();
        connectionManager.setMaxTotal(200);
        connectionManager.setDefaultMaxPerRoute(50);
        connectionManager.setValidateAfterInactivity(2000);
        
        // 2. 配置超時
        RequestConfig requestConfig = RequestConfig.custom()
                .setConnectionRequestTimeout(5000)
                .setConnectTimeout(5000)
                .setSocketTimeout(30000)
                .build();
        
        // 3. 配置重試
        HttpRequestRetryHandler retryHandler = new DefaultHttpRequestRetryHandler(3, true);
        
        // 4. 配置 Keep-Alive
        ConnectionKeepAliveStrategy keepAliveStrategy = (response, context) -> 30 * 1000;
        
        CloseableHttpClient httpClient = HttpClients.custom()
                .setConnectionManager(connectionManager)
                .setDefaultRequestConfig(requestConfig)
                .setRetryHandler(retryHandler)
                .setKeepAliveStrategy(keepAliveStrategy)
                .build();
        
        HttpComponentsClientHttpRequestFactory factory = new HttpComponentsClientHttpRequestFactory(httpClient);
        
        RestTemplate restTemplate = new RestTemplate(factory);
        
        // 5. 添加攔截器
        restTemplate.setInterceptors(Arrays.asList(
                new LoggingInterceptor(),
                new MetricsInterceptor(meterRegistry),
                new AuthenticationInterceptor(tokenService)
        ));
        
        // 6. 設置錯誤處理器
        restTemplate.setErrorHandler(new CustomResponseErrorHandler());
        
        return restTemplate;
    }
    
    /**
     * 常見錯誤和解決方案
     */
    public void demonstrateCommonPitfalls() {
        // ❌ 錯誤：未設置超時
        RestTemplate badTemplate = new RestTemplate();
        
        // ✅ 正確：設置合理的超時
        SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
        factory.setConnectTimeout(5000);
        factory.setReadTimeout(30000);
        RestTemplate goodTemplate = new RestTemplate(factory);
        
        // ❌ 錯誤：未使用連接池
        // 每次請求都創建新連接
        
        // ✅ 正確：使用連接池復用連接
        // 見上面的生產環境配置
        
        // ❌ 錯誤：未處理異常
        try {
            String result = badTemplate.getForObject("http://api.example.com/data", String.class);
        } catch (Exception e) {
            // 直接忽略異常
        }
        
        // ✅ 正確：適當的異常處理
        try {
            String result = goodTemplate.getForObject("http://api.example.com/data", String.class);
        } catch (ResourceAccessException e) {
            logger.error("Network error", e);
            throw new ServiceUnavailableException("Service temporarily unavailable");
        } catch (HttpClientErrorException e) {
            logger.error("Client error: {}", e.getStatusCode(), e);
            throw new BadRequestException("Invalid request");
        }
    }
}

2. 安全性考量

/**
 * RestTemplate 安全配置
 */
@Configuration
public class SecureRestTemplateConfig {
    
    /**
     * HTTPS 配置
     */
    @Bean
    public RestTemplate secureRestTemplate() throws Exception {
        TrustStrategy acceptingTrustStrategy = (X509Certificate[] chain, String authType) -> true;
        
        SSLContext sslContext = org.apache.http.ssl.SSLContexts.custom()
                .loadTrustMaterial(null, acceptingTrustStrategy)
                .build();
        
        SSLConnectionSocketFactory csf = new SSLConnectionSocketFactory(sslContext);
        
        CloseableHttpClient httpClient = HttpClients.custom()
                .setSSLSocketFactory(csf)
                .build();
        
        HttpComponentsClientHttpRequestFactory requestFactory = 
                new HttpComponentsClientHttpRequestFactory();
        requestFactory.setHttpClient(httpClient);
        
        return new RestTemplate(requestFactory);
    }
    
    /**
     * 認證配置
     */
    @Component
    public class SecureAuthInterceptor implements ClientHttpRequestInterceptor {
        
        @Override
        public ClientHttpResponse intercept(
                HttpRequest request, 
                byte[] body, 
                ClientHttpRequestExecution execution) throws IOException {
            
            // 1. 添加 API Key
            request.getHeaders().set("X-API-Key", getApiKey());
            
            // 2. 添加請求簽名
            String signature = generateSignature(request, body);
            request.getHeaders().set("X-Signature", signature);
            
            // 3. 添加時間戳防重放
            request.getHeaders().set("X-Timestamp", String.valueOf(System.currentTimeMillis()));
            
            return execution.execute(request, body);
        }
        
        private String getApiKey() {
            // 從安全配置中獲取 API Key
            return securityConfig.getApiKey();
        }
        
        private String generateSignature(HttpRequest request, byte[] body) {
            // 實作請求簽名邏輯
            return hmacSha256(request.getURI() + new String(body), getSecretKey());
        }
    }
}

總結

RestTemplate 作為 Spring 生態系統中的經典 HTTP 客戶端，提供了豐富的功能和良好的擴展性：