Java后端服务集成伏羲气象API微服务架构设计与实现最近在做一个智慧园区项目需要实时获取天气数据来调整空调能耗和安防策略。一开始我们直接在前端调用气象API结果发现页面加载慢不说还经常因为网络波动导致数据获取失败。后来我们决定把气象服务集成到后端用微服务的方式统一管理这下稳定性和性能都上来了。今天就跟大家聊聊怎么在一个标准的Spring Boot微服务里优雅地集成像伏羲这样的气象API。我会从接口设计讲到缓存策略再到异常处理把我们在实际项目中踩过的坑和总结的经验都分享出来。1. 为什么要在后端集成气象API你可能觉得在前端直接调用API多简单何必绕到后端我们一开始也是这么想的但实际用起来问题不少。前端直接调用的话每个用户的浏览器都要单独发起请求如果用户量一大对气象API的调用次数就上去了很容易触发频率限制。而且前端网络环境复杂在移动网络下请求失败率很高用户看到的就是一片空白或者加载中。放到后端做就不一样了。我们可以把多个用户的请求合并一次调用拿到数据后分发给所有人。还能加缓存半小时内的天气数据基本不变没必要每次都去问API。更重要的是后端可以做熔断和降级就算气象服务暂时不可用我们也能返回缓存的历史数据或者默认值保证主业务不受影响。我们项目里用了之后天气数据获取的失败率从原来的15%降到了几乎为零页面加载时间也快了将近一倍。2. 服务层设计与接口封装先把架子搭好后面写代码就顺畅了。我们的核心思路是把第三方API的细节封装起来对外提供干净、稳定的服务。2.1 定义清晰的数据模型第一步不是急着写调用代码而是先想好数据怎么存、怎么传。气象API返回的数据往往很详细但我们业务可能只需要其中几项。// 对外暴露的简洁天气数据模型 Data public class WeatherDTO { private String cityCode; private String cityName; private String weatherCondition; // 如晴、多云、小雨 private Integer temperature; // 温度单位摄氏度 private Integer humidity; // 湿度百分比 private String windDirection; // 风向 private Integer windPower; // 风力等级 private String updateTime; // 数据更新时间 } // 内部使用的、包含更多细节的模型 Data public class WeatherDetailVO { private String cityCode; // ... 其他基础字段同WeatherDTO // 扩展字段 private Integer feelsLike; // 体感温度 private Integer pressure; // 气压 private String visibility; // 能见度 private ListHourlyForecast hourlyForecasts; // 逐小时预报 private ListDailyForecast dailyForecasts; // 未来几天预报 Data public static class HourlyForecast { private String time; private String weather; private Integer temp; private Integer humidity; } Data public static class DailyForecast { private String date; private String dayWeather; private String nightWeather; private Integer maxTemp; private Integer minTemp; } }这样设计有个好处服务层内部处理用详细的WeatherDetailVO但给控制器返回的是精简的WeatherDTO。前端不用关心那些复杂的预报数据加载更快数据结构也清晰。2.2 设计服务接口接口设计要考虑到不同场景的需求。有时候我们只需要当前天气有时候需要未来几天的预报。public interface WeatherService { /** * 获取实时天气核心方法 */ WeatherDTO getCurrentWeather(String cityCode); /** * 批量获取多个城市的天气 */ MapString, WeatherDTO batchGetWeather(ListString cityCodes); /** * 获取天气预报未来几天 */ WeatherForecastDTO getWeatherForecast(String cityCode, Integer days); /** * 刷新缓存管理用 */ void refreshCache(String cityCode); }3. 第三方API调用封装这是最核心的部分怎么把伏羲气象API的调用做得稳定又高效。3.1 配置管理不要把API密钥、地址这些信息硬编码在代码里。我们用Spring Boot的配置机制来管理。# application.yml weather: fuxi: api: base-url: https://api.fuxi-weather.com/v3 app-key: ${WEATHER_APP_KEY:your_default_key_here} app-secret: ${WEATHER_APP_SECRET:} config: timeout: 5000 # 超时时间5秒 retry-times: 2 # 失败重试2次 cache-ttl: 1800 # 缓存30分钟1800秒对应的配置类Configuration ConfigurationProperties(prefix weather.fuxi) Data public class WeatherConfig { private ApiConfig api; private ServiceConfig config; Data public static class ApiConfig { private String baseUrl; private String appKey; private String appSecret; } Data public static class ServiceConfig { private Integer timeout; private Integer retryTimes; private Integer cacheTtl; } }3.2 HTTP客户端封装我们用的是RestTemplate但做了些增强处理。你也可以用WebClient特别是如果你在用Spring WebFlux。Component Slf4j public class WeatherApiClient { Autowired private RestTemplate restTemplate; Autowired private WeatherConfig weatherConfig; /** * 调用实时天气接口 */ public WeatherDetailVO fetchCurrentWeather(String cityCode) { String url buildUrl(/weather/current, cityCode); try { ResponseEntityMap response restTemplate.getForEntity(url, Map.class); if (response.getStatusCode().is2xxSuccessful() response.getBody() ! null) { return convertToWeatherDetail(response.getBody()); } else { log.warn(获取天气数据失败城市: {}, 状态码: {}, cityCode, response.getStatusCode()); throw new WeatherApiException(气象API返回异常状态); } } catch (ResourceAccessException e) { log.error(调用气象API超时或网络异常城市: {}, cityCode, e); throw new WeatherApiException(网络超时请稍后重试); } catch (Exception e) { log.error(调用气象API未知异常城市: {}, cityCode, e); throw new WeatherApiException(获取天气数据失败); } } /** * 构建带签名的请求URL */ private String buildUrl(String path, String cityCode) { String timestamp String.valueOf(System.currentTimeMillis() / 1000); String sign generateSign(cityCode, timestamp); return String.format(%s%s?city%sappkey%stimestamp%ssign%s, weatherConfig.getApi().getBaseUrl(), path, cityCode, weatherConfig.getApi().getAppKey(), timestamp, sign); } /** * 生成请求签名示例逻辑实际根据API文档实现 */ private String generateSign(String cityCode, String timestamp) { String raw cityCode timestamp weatherConfig.getApi().getAppSecret(); return DigestUtils.md5DigestAsHex(raw.getBytes()); } /** * 转换API响应到我们的数据模型 */ private WeatherDetailVO convertToWeatherDetail(MapString, Object apiResponse) { // 这里根据实际API响应结构解析 WeatherDetailVO detail new WeatherDetailVO(); MapString, Object data (MapString, Object) apiResponse.get(data); if (data ! null) { detail.setCityCode((String) data.get(city_code)); detail.setCityName((String) data.get(city_name)); detail.setWeatherCondition((String) data.get(weather)); detail.setTemperature(((Number) data.get(temp)).intValue()); // ... 设置其他字段 } return detail; } }这里有个关键点异常处理。第三方API可能因为各种原因失败我们要把不同的异常转换成业务能理解的异常类型而不是直接把HTTP异常抛出去。4. 缓存策略实现天气数据变化没那么快完全没必要每次都调用API。加缓存能大幅降低API调用次数提升响应速度。4.1 使用Redis做二级缓存我们用内存缓存Redis的两级缓存策略。内存缓存响应最快Redis保证分布式环境下数据一致。Service Slf4j public class WeatherServiceImpl implements WeatherService { // 本地缓存使用Caffeine private final CacheString, WeatherDTO localCache Caffeine.newBuilder() .expireAfterWrite(5, TimeUnit.MINUTES) // 5分钟过期 .maximumSize(1000) // 最多缓存1000个城市 .build(); Autowired private RedisTemplateString, WeatherDTO redisTemplate; Autowired private WeatherApiClient weatherApiClient; Autowired private WeatherConfig weatherConfig; private static final String REDIS_KEY_PREFIX weather:current:; Override public WeatherDTO getCurrentWeather(String cityCode) { // 1. 先查本地缓存 WeatherDTO cached localCache.getIfPresent(cityCode); if (cached ! null) { log.debug(从本地缓存命中天气数据城市: {}, cityCode); return cached; } // 2. 查Redis缓存 String redisKey REDIS_KEY_PREFIX cityCode; cached redisTemplate.opsForValue().get(redisKey); if (cached ! null) { log.debug(从Redis缓存命中天气数据城市: {}, cityCode); localCache.put(cityCode, cached); // 回填本地缓存 return cached; } // 3. 缓存都没有调用API log.info(缓存未命中调用气象API获取数据城市: {}, cityCode); WeatherDetailVO detail weatherApiClient.fetchCurrentWeather(cityCode); WeatherDTO result convertToDTO(detail); // 4. 更新缓存 updateCache(cityCode, result); return result; } /** * 批量查询 - 更高效的方式 */ Override public MapString, WeatherDTO batchGetWeather(ListString cityCodes) { MapString, WeatherDTO result new HashMap(); ListString missingCities new ArrayList(); // 第一轮从本地缓存查 for (String cityCode : cityCodes) { WeatherDTO cached localCache.getIfPresent(cityCode); if (cached ! null) { result.put(cityCode, cached); } else { missingCities.add(cityCode); } } if (missingCities.isEmpty()) { return result; // 全部命中本地缓存 } // 第二轮批量从Redis查 ListString redisKeys missingCities.stream() .map(city - REDIS_KEY_PREFIX city) .collect(Collectors.toList()); ListWeatherDTO redisResults redisTemplate.opsForValue().multiGet(redisKeys); for (int i 0; i missingCities.size(); i) { String cityCode missingCities.get(i); WeatherDTO redisData redisResults.get(i); if (redisData ! null) { result.put(cityCode, redisData); localCache.put(cityCode, redisData); // 回填本地缓存 } else { // 还是没查到标记需要调用API result.put(cityCode, null); } } // 第三轮异步调用API补全缺失数据 completeMissingDataAsync(result); return result; } /** * 异步补全缺失的天气数据 */ Async public void completeMissingDataAsync(MapString, WeatherDTO result) { result.entrySet().stream() .filter(entry - entry.getValue() null) .forEach(entry - { String cityCode entry.getKey(); try { WeatherDetailVO detail weatherApiClient.fetchCurrentWeather(cityCode); WeatherDTO weather convertToDTO(detail); entry.setValue(weather); updateCache(cityCode, weather); } catch (Exception e) { log.error(异步获取天气数据失败城市: {}, cityCode, e); // 可以设置一个默认值或保持null } }); } /** * 更新两级缓存 */ private void updateCache(String cityCode, WeatherDTO weather) { // 更新本地缓存 localCache.put(cityCode, weather); // 更新Redis设置过期时间 String redisKey REDIS_KEY_PREFIX cityCode; redisTemplate.opsForValue().set( redisKey, weather, weatherConfig.getConfig().getCacheTtl(), TimeUnit.SECONDS ); } }批量查询这里有个小技巧不是每个城市单独查而是先批量从缓存捞剩下的再批量调用API。这样能减少网络请求次数特别是当你有几十个城市要查的时候性能提升很明显。5. 熔断降级与异常处理气象API不是我们自己的服务难免会有不稳定的时候。要做好防护不能让第三方服务的问题影响到我们自己的系统。5.1 使用Resilience4j实现熔断Configuration public class CircuitBreakerConfig { Bean public CircuitBreakerRegistry circuitBreakerRegistry() { CircuitBreakerConfig config CircuitBreakerConfig.custom() .failureRateThreshold(50) // 失败率阈值50% .waitDurationInOpenState(Duration.ofSeconds(30)) // 熔断后30秒进入半开状态 .slidingWindowSize(10) // 基于最近10次调用计算 .permittedNumberOfCallsInHalfOpenState(3) // 半开状态下允许3次调用 .build(); return CircuitBreakerRegistry.of(config); } Bean public CircuitBreaker weatherCircuitBreaker(CircuitBreakerRegistry registry) { return registry.circuitBreaker(weatherApi); } } Service public class WeatherServiceWithCircuitBreaker { Autowired private CircuitBreaker circuitBreaker; Autowired private WeatherApiClient weatherApiClient; public WeatherDetailVO getWeatherWithCircuitBreaker(String cityCode) { return circuitBreaker.executeSupplier(() - { return weatherApiClient.fetchCurrentWeather(cityCode); }); } /** * 带降级逻辑的调用 */ public WeatherDTO getWeatherWithFallback(String cityCode) { try { WeatherDetailVO detail circuitBreaker.executeSupplier(() - { return weatherApiClient.fetchCurrentWeather(cityCode); }); return convertToDTO(detail); } catch (Exception e) { log.warn(气象API调用失败使用降级方案城市: {}, cityCode, e); return getFallbackWeather(cityCode); } } /** * 降级方案返回缓存数据或默认值 */ private WeatherDTO getFallbackWeather(String cityCode) { // 1. 先尝试从缓存获取可能是稍旧的数据 WeatherDTO cached getFromCache(cityCode); if (cached ! null) { cached.setSource(cache); // 标记数据来源 return cached; } // 2. 缓存也没有返回默认值 return createDefaultWeather(cityCode); } }5.2 统一异常处理不要让第三方服务的异常直接暴露给前端。我们做个统一的异常转换。RestControllerAdvice Slf4j public class GlobalExceptionHandler { /** * 处理业务异常 */ ExceptionHandler(WeatherServiceException.class) public ResponseEntityApiResponse? handleWeatherException(WeatherServiceException e) { log.warn(业务异常: {}, e.getMessage()); ApiResponse? response ApiResponse.error( e.getErrorCode(), e.getMessage() ); return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response); } /** * 处理第三方API异常 */ ExceptionHandler(WeatherApiException.class) public ResponseEntityApiResponse? handleApiException(WeatherApiException e) { log.error(气象API异常, e); ApiResponse? response ApiResponse.error( WEATHER_API_ERROR, 天气服务暂时不可用请稍后重试 ); return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).body(response); } /** * 处理所有其他异常 */ ExceptionHandler(Exception.class) public ResponseEntityApiResponse? handleGenericException(Exception e) { log.error(系统异常, e); ApiResponse? response ApiResponse.error( INTERNAL_ERROR, 系统繁忙请稍后重试 ); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response); } } // 统一的API响应格式 Data AllArgsConstructor public class ApiResponseT { private boolean success; private String code; private String message; private T data; private Long timestamp; public static T ApiResponseT success(T data) { return new ApiResponse(true, SUCCESS, 操作成功, data, System.currentTimeMillis()); } public static T ApiResponseT error(String code, String message) { return new ApiResponse(false, code, message, null, System.currentTimeMillis()); } }6. 实战完整的RESTful接口最后把这些组件组合起来提供一个完整的RESTful接口。RestController RequestMapping(/api/weather) Validated Slf4j public class WeatherController { Autowired private WeatherService weatherService; /** * 获取单个城市天气 */ GetMapping(/current/{cityCode}) public ApiResponseWeatherDTO getCurrentWeather( PathVariable NotBlank String cityCode, RequestParam(required false) Boolean refresh) { log.info(获取天气数据城市: {}, 强制刷新: {}, cityCode, refresh); if (Boolean.TRUE.equals(refresh)) { weatherService.refreshCache(cityCode); } WeatherDTO weather weatherService.getCurrentWeather(cityCode); return ApiResponse.success(weather); } /** * 批量获取天气数据 */ PostMapping(/batch-current) public ApiResponseMapString, WeatherDTO batchGetWeather( RequestBody Valid BatchWeatherRequest request) { log.info(批量获取天气数据城市数量: {}, request.getCityCodes().size()); MapString, WeatherDTO result weatherService.batchGetWeather(request.getCityCodes()); return ApiResponse.success(result); } /** * 获取天气预报 */ GetMapping(/forecast/{cityCode}) public ApiResponseWeatherForecastDTO getForecast( PathVariable String cityCode, RequestParam(defaultValue 3) Integer days) { if (days 1 || days 7) { throw new IllegalArgumentException(预报天数必须在1-7之间); } WeatherForecastDTO forecast weatherService.getWeatherForecast(cityCode, days); return ApiResponse.success(forecast); } } // 批量请求参数 Data class BatchWeatherRequest { NotEmpty(message 城市编码列表不能为空) Size(max 50, message 一次最多查询50个城市) private ListString cityCodes; }7. 部署与监控建议服务写好了怎么部署和监控才能保证稳定运行配置方面建议把超时时间设得短一点比如3-5秒。天气数据不是实时交易稍微旧一点的数据用户也能接受但要是因为超时导致整个请求卡住就不划算了。监控方面这几个指标要重点关注API调用成功率低于95%就要报警了平均响应时间如果突然变长可能是API服务有问题缓存命中率太高说明缓存时间可能设得太长数据不新鲜太低又失去了缓存的意义熔断器状态如果经常熔断要么是API不稳定要么是我们的配置太敏感日志记录也很重要。每次调用API都要记日志包括请求参数、响应时间、是否成功。出问题的时候这些日志能帮你快速定位。我们项目里还加了个健康检查接口定时去调一下气象API看看服务是不是正常。如果连续失败就在监控系统里告警。8. 总结把气象API集成到Java后端服务看起来简单但要做得稳定、高效还是有不少细节要注意的。关键是要有缓存这是提升性能和降低API调用量的最有效方法。我们用的是内存Redis两级缓存内存缓存响应快Redis保证分布式一致。批量查询也要优化尽量一次多查几个城市减少网络开销。异常处理不能马虎。第三方服务说不准什么时候就出问题熔断、降级、超时控制这些机制都得配上。就算气象API完全不可用我们至少还能返回缓存里的旧数据或者给个默认值不至于让整个页面卡住。监控也得跟上。成功率、响应时间、缓存命中率这些指标要实时看着有问题早发现早处理。实际做下来这套方案在我们生产环境跑了一年多一直挺稳定的。天气服务的可用性做到了99.9%以上平均响应时间在100毫秒以内业务方反馈也不错。如果你也在做类似的功能可以参考这个思路根据你们的实际情况调整调整。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
Java后端服务集成伏羲气象API：微服务架构设计与实现
Java后端服务集成伏羲气象API微服务架构设计与实现最近在做一个智慧园区项目需要实时获取天气数据来调整空调能耗和安防策略。一开始我们直接在前端调用气象API结果发现页面加载慢不说还经常因为网络波动导致数据获取失败。后来我们决定把气象服务集成到后端用微服务的方式统一管理这下稳定性和性能都上来了。今天就跟大家聊聊怎么在一个标准的Spring Boot微服务里优雅地集成像伏羲这样的气象API。我会从接口设计讲到缓存策略再到异常处理把我们在实际项目中踩过的坑和总结的经验都分享出来。1. 为什么要在后端集成气象API你可能觉得在前端直接调用API多简单何必绕到后端我们一开始也是这么想的但实际用起来问题不少。前端直接调用的话每个用户的浏览器都要单独发起请求如果用户量一大对气象API的调用次数就上去了很容易触发频率限制。而且前端网络环境复杂在移动网络下请求失败率很高用户看到的就是一片空白或者加载中。放到后端做就不一样了。我们可以把多个用户的请求合并一次调用拿到数据后分发给所有人。还能加缓存半小时内的天气数据基本不变没必要每次都去问API。更重要的是后端可以做熔断和降级就算气象服务暂时不可用我们也能返回缓存的历史数据或者默认值保证主业务不受影响。我们项目里用了之后天气数据获取的失败率从原来的15%降到了几乎为零页面加载时间也快了将近一倍。2. 服务层设计与接口封装先把架子搭好后面写代码就顺畅了。我们的核心思路是把第三方API的细节封装起来对外提供干净、稳定的服务。2.1 定义清晰的数据模型第一步不是急着写调用代码而是先想好数据怎么存、怎么传。气象API返回的数据往往很详细但我们业务可能只需要其中几项。// 对外暴露的简洁天气数据模型 Data public class WeatherDTO { private String cityCode; private String cityName; private String weatherCondition; // 如晴、多云、小雨 private Integer temperature; // 温度单位摄氏度 private Integer humidity; // 湿度百分比 private String windDirection; // 风向 private Integer windPower; // 风力等级 private String updateTime; // 数据更新时间 } // 内部使用的、包含更多细节的模型 Data public class WeatherDetailVO { private String cityCode; // ... 其他基础字段同WeatherDTO // 扩展字段 private Integer feelsLike; // 体感温度 private Integer pressure; // 气压 private String visibility; // 能见度 private ListHourlyForecast hourlyForecasts; // 逐小时预报 private ListDailyForecast dailyForecasts; // 未来几天预报 Data public static class HourlyForecast { private String time; private String weather; private Integer temp; private Integer humidity; } Data public static class DailyForecast { private String date; private String dayWeather; private String nightWeather; private Integer maxTemp; private Integer minTemp; } }这样设计有个好处服务层内部处理用详细的WeatherDetailVO但给控制器返回的是精简的WeatherDTO。前端不用关心那些复杂的预报数据加载更快数据结构也清晰。2.2 设计服务接口接口设计要考虑到不同场景的需求。有时候我们只需要当前天气有时候需要未来几天的预报。public interface WeatherService { /** * 获取实时天气核心方法 */ WeatherDTO getCurrentWeather(String cityCode); /** * 批量获取多个城市的天气 */ MapString, WeatherDTO batchGetWeather(ListString cityCodes); /** * 获取天气预报未来几天 */ WeatherForecastDTO getWeatherForecast(String cityCode, Integer days); /** * 刷新缓存管理用 */ void refreshCache(String cityCode); }3. 第三方API调用封装这是最核心的部分怎么把伏羲气象API的调用做得稳定又高效。3.1 配置管理不要把API密钥、地址这些信息硬编码在代码里。我们用Spring Boot的配置机制来管理。# application.yml weather: fuxi: api: base-url: https://api.fuxi-weather.com/v3 app-key: ${WEATHER_APP_KEY:your_default_key_here} app-secret: ${WEATHER_APP_SECRET:} config: timeout: 5000 # 超时时间5秒 retry-times: 2 # 失败重试2次 cache-ttl: 1800 # 缓存30分钟1800秒对应的配置类Configuration ConfigurationProperties(prefix weather.fuxi) Data public class WeatherConfig { private ApiConfig api; private ServiceConfig config; Data public static class ApiConfig { private String baseUrl; private String appKey; private String appSecret; } Data public static class ServiceConfig { private Integer timeout; private Integer retryTimes; private Integer cacheTtl; } }3.2 HTTP客户端封装我们用的是RestTemplate但做了些增强处理。你也可以用WebClient特别是如果你在用Spring WebFlux。Component Slf4j public class WeatherApiClient { Autowired private RestTemplate restTemplate; Autowired private WeatherConfig weatherConfig; /** * 调用实时天气接口 */ public WeatherDetailVO fetchCurrentWeather(String cityCode) { String url buildUrl(/weather/current, cityCode); try { ResponseEntityMap response restTemplate.getForEntity(url, Map.class); if (response.getStatusCode().is2xxSuccessful() response.getBody() ! null) { return convertToWeatherDetail(response.getBody()); } else { log.warn(获取天气数据失败城市: {}, 状态码: {}, cityCode, response.getStatusCode()); throw new WeatherApiException(气象API返回异常状态); } } catch (ResourceAccessException e) { log.error(调用气象API超时或网络异常城市: {}, cityCode, e); throw new WeatherApiException(网络超时请稍后重试); } catch (Exception e) { log.error(调用气象API未知异常城市: {}, cityCode, e); throw new WeatherApiException(获取天气数据失败); } } /** * 构建带签名的请求URL */ private String buildUrl(String path, String cityCode) { String timestamp String.valueOf(System.currentTimeMillis() / 1000); String sign generateSign(cityCode, timestamp); return String.format(%s%s?city%sappkey%stimestamp%ssign%s, weatherConfig.getApi().getBaseUrl(), path, cityCode, weatherConfig.getApi().getAppKey(), timestamp, sign); } /** * 生成请求签名示例逻辑实际根据API文档实现 */ private String generateSign(String cityCode, String timestamp) { String raw cityCode timestamp weatherConfig.getApi().getAppSecret(); return DigestUtils.md5DigestAsHex(raw.getBytes()); } /** * 转换API响应到我们的数据模型 */ private WeatherDetailVO convertToWeatherDetail(MapString, Object apiResponse) { // 这里根据实际API响应结构解析 WeatherDetailVO detail new WeatherDetailVO(); MapString, Object data (MapString, Object) apiResponse.get(data); if (data ! null) { detail.setCityCode((String) data.get(city_code)); detail.setCityName((String) data.get(city_name)); detail.setWeatherCondition((String) data.get(weather)); detail.setTemperature(((Number) data.get(temp)).intValue()); // ... 设置其他字段 } return detail; } }这里有个关键点异常处理。第三方API可能因为各种原因失败我们要把不同的异常转换成业务能理解的异常类型而不是直接把HTTP异常抛出去。4. 缓存策略实现天气数据变化没那么快完全没必要每次都调用API。加缓存能大幅降低API调用次数提升响应速度。4.1 使用Redis做二级缓存我们用内存缓存Redis的两级缓存策略。内存缓存响应最快Redis保证分布式环境下数据一致。Service Slf4j public class WeatherServiceImpl implements WeatherService { // 本地缓存使用Caffeine private final CacheString, WeatherDTO localCache Caffeine.newBuilder() .expireAfterWrite(5, TimeUnit.MINUTES) // 5分钟过期 .maximumSize(1000) // 最多缓存1000个城市 .build(); Autowired private RedisTemplateString, WeatherDTO redisTemplate; Autowired private WeatherApiClient weatherApiClient; Autowired private WeatherConfig weatherConfig; private static final String REDIS_KEY_PREFIX weather:current:; Override public WeatherDTO getCurrentWeather(String cityCode) { // 1. 先查本地缓存 WeatherDTO cached localCache.getIfPresent(cityCode); if (cached ! null) { log.debug(从本地缓存命中天气数据城市: {}, cityCode); return cached; } // 2. 查Redis缓存 String redisKey REDIS_KEY_PREFIX cityCode; cached redisTemplate.opsForValue().get(redisKey); if (cached ! null) { log.debug(从Redis缓存命中天气数据城市: {}, cityCode); localCache.put(cityCode, cached); // 回填本地缓存 return cached; } // 3. 缓存都没有调用API log.info(缓存未命中调用气象API获取数据城市: {}, cityCode); WeatherDetailVO detail weatherApiClient.fetchCurrentWeather(cityCode); WeatherDTO result convertToDTO(detail); // 4. 更新缓存 updateCache(cityCode, result); return result; } /** * 批量查询 - 更高效的方式 */ Override public MapString, WeatherDTO batchGetWeather(ListString cityCodes) { MapString, WeatherDTO result new HashMap(); ListString missingCities new ArrayList(); // 第一轮从本地缓存查 for (String cityCode : cityCodes) { WeatherDTO cached localCache.getIfPresent(cityCode); if (cached ! null) { result.put(cityCode, cached); } else { missingCities.add(cityCode); } } if (missingCities.isEmpty()) { return result; // 全部命中本地缓存 } // 第二轮批量从Redis查 ListString redisKeys missingCities.stream() .map(city - REDIS_KEY_PREFIX city) .collect(Collectors.toList()); ListWeatherDTO redisResults redisTemplate.opsForValue().multiGet(redisKeys); for (int i 0; i missingCities.size(); i) { String cityCode missingCities.get(i); WeatherDTO redisData redisResults.get(i); if (redisData ! null) { result.put(cityCode, redisData); localCache.put(cityCode, redisData); // 回填本地缓存 } else { // 还是没查到标记需要调用API result.put(cityCode, null); } } // 第三轮异步调用API补全缺失数据 completeMissingDataAsync(result); return result; } /** * 异步补全缺失的天气数据 */ Async public void completeMissingDataAsync(MapString, WeatherDTO result) { result.entrySet().stream() .filter(entry - entry.getValue() null) .forEach(entry - { String cityCode entry.getKey(); try { WeatherDetailVO detail weatherApiClient.fetchCurrentWeather(cityCode); WeatherDTO weather convertToDTO(detail); entry.setValue(weather); updateCache(cityCode, weather); } catch (Exception e) { log.error(异步获取天气数据失败城市: {}, cityCode, e); // 可以设置一个默认值或保持null } }); } /** * 更新两级缓存 */ private void updateCache(String cityCode, WeatherDTO weather) { // 更新本地缓存 localCache.put(cityCode, weather); // 更新Redis设置过期时间 String redisKey REDIS_KEY_PREFIX cityCode; redisTemplate.opsForValue().set( redisKey, weather, weatherConfig.getConfig().getCacheTtl(), TimeUnit.SECONDS ); } }批量查询这里有个小技巧不是每个城市单独查而是先批量从缓存捞剩下的再批量调用API。这样能减少网络请求次数特别是当你有几十个城市要查的时候性能提升很明显。5. 熔断降级与异常处理气象API不是我们自己的服务难免会有不稳定的时候。要做好防护不能让第三方服务的问题影响到我们自己的系统。5.1 使用Resilience4j实现熔断Configuration public class CircuitBreakerConfig { Bean public CircuitBreakerRegistry circuitBreakerRegistry() { CircuitBreakerConfig config CircuitBreakerConfig.custom() .failureRateThreshold(50) // 失败率阈值50% .waitDurationInOpenState(Duration.ofSeconds(30)) // 熔断后30秒进入半开状态 .slidingWindowSize(10) // 基于最近10次调用计算 .permittedNumberOfCallsInHalfOpenState(3) // 半开状态下允许3次调用 .build(); return CircuitBreakerRegistry.of(config); } Bean public CircuitBreaker weatherCircuitBreaker(CircuitBreakerRegistry registry) { return registry.circuitBreaker(weatherApi); } } Service public class WeatherServiceWithCircuitBreaker { Autowired private CircuitBreaker circuitBreaker; Autowired private WeatherApiClient weatherApiClient; public WeatherDetailVO getWeatherWithCircuitBreaker(String cityCode) { return circuitBreaker.executeSupplier(() - { return weatherApiClient.fetchCurrentWeather(cityCode); }); } /** * 带降级逻辑的调用 */ public WeatherDTO getWeatherWithFallback(String cityCode) { try { WeatherDetailVO detail circuitBreaker.executeSupplier(() - { return weatherApiClient.fetchCurrentWeather(cityCode); }); return convertToDTO(detail); } catch (Exception e) { log.warn(气象API调用失败使用降级方案城市: {}, cityCode, e); return getFallbackWeather(cityCode); } } /** * 降级方案返回缓存数据或默认值 */ private WeatherDTO getFallbackWeather(String cityCode) { // 1. 先尝试从缓存获取可能是稍旧的数据 WeatherDTO cached getFromCache(cityCode); if (cached ! null) { cached.setSource(cache); // 标记数据来源 return cached; } // 2. 缓存也没有返回默认值 return createDefaultWeather(cityCode); } }5.2 统一异常处理不要让第三方服务的异常直接暴露给前端。我们做个统一的异常转换。RestControllerAdvice Slf4j public class GlobalExceptionHandler { /** * 处理业务异常 */ ExceptionHandler(WeatherServiceException.class) public ResponseEntityApiResponse? handleWeatherException(WeatherServiceException e) { log.warn(业务异常: {}, e.getMessage()); ApiResponse? response ApiResponse.error( e.getErrorCode(), e.getMessage() ); return ResponseEntity.status(HttpStatus.BAD_REQUEST).body(response); } /** * 处理第三方API异常 */ ExceptionHandler(WeatherApiException.class) public ResponseEntityApiResponse? handleApiException(WeatherApiException e) { log.error(气象API异常, e); ApiResponse? response ApiResponse.error( WEATHER_API_ERROR, 天气服务暂时不可用请稍后重试 ); return ResponseEntity.status(HttpStatus.SERVICE_UNAVAILABLE).body(response); } /** * 处理所有其他异常 */ ExceptionHandler(Exception.class) public ResponseEntityApiResponse? handleGenericException(Exception e) { log.error(系统异常, e); ApiResponse? response ApiResponse.error( INTERNAL_ERROR, 系统繁忙请稍后重试 ); return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(response); } } // 统一的API响应格式 Data AllArgsConstructor public class ApiResponseT { private boolean success; private String code; private String message; private T data; private Long timestamp; public static T ApiResponseT success(T data) { return new ApiResponse(true, SUCCESS, 操作成功, data, System.currentTimeMillis()); } public static T ApiResponseT error(String code, String message) { return new ApiResponse(false, code, message, null, System.currentTimeMillis()); } }6. 实战完整的RESTful接口最后把这些组件组合起来提供一个完整的RESTful接口。RestController RequestMapping(/api/weather) Validated Slf4j public class WeatherController { Autowired private WeatherService weatherService; /** * 获取单个城市天气 */ GetMapping(/current/{cityCode}) public ApiResponseWeatherDTO getCurrentWeather( PathVariable NotBlank String cityCode, RequestParam(required false) Boolean refresh) { log.info(获取天气数据城市: {}, 强制刷新: {}, cityCode, refresh); if (Boolean.TRUE.equals(refresh)) { weatherService.refreshCache(cityCode); } WeatherDTO weather weatherService.getCurrentWeather(cityCode); return ApiResponse.success(weather); } /** * 批量获取天气数据 */ PostMapping(/batch-current) public ApiResponseMapString, WeatherDTO batchGetWeather( RequestBody Valid BatchWeatherRequest request) { log.info(批量获取天气数据城市数量: {}, request.getCityCodes().size()); MapString, WeatherDTO result weatherService.batchGetWeather(request.getCityCodes()); return ApiResponse.success(result); } /** * 获取天气预报 */ GetMapping(/forecast/{cityCode}) public ApiResponseWeatherForecastDTO getForecast( PathVariable String cityCode, RequestParam(defaultValue 3) Integer days) { if (days 1 || days 7) { throw new IllegalArgumentException(预报天数必须在1-7之间); } WeatherForecastDTO forecast weatherService.getWeatherForecast(cityCode, days); return ApiResponse.success(forecast); } } // 批量请求参数 Data class BatchWeatherRequest { NotEmpty(message 城市编码列表不能为空) Size(max 50, message 一次最多查询50个城市) private ListString cityCodes; }7. 部署与监控建议服务写好了怎么部署和监控才能保证稳定运行配置方面建议把超时时间设得短一点比如3-5秒。天气数据不是实时交易稍微旧一点的数据用户也能接受但要是因为超时导致整个请求卡住就不划算了。监控方面这几个指标要重点关注API调用成功率低于95%就要报警了平均响应时间如果突然变长可能是API服务有问题缓存命中率太高说明缓存时间可能设得太长数据不新鲜太低又失去了缓存的意义熔断器状态如果经常熔断要么是API不稳定要么是我们的配置太敏感日志记录也很重要。每次调用API都要记日志包括请求参数、响应时间、是否成功。出问题的时候这些日志能帮你快速定位。我们项目里还加了个健康检查接口定时去调一下气象API看看服务是不是正常。如果连续失败就在监控系统里告警。8. 总结把气象API集成到Java后端服务看起来简单但要做得稳定、高效还是有不少细节要注意的。关键是要有缓存这是提升性能和降低API调用量的最有效方法。我们用的是内存Redis两级缓存内存缓存响应快Redis保证分布式一致。批量查询也要优化尽量一次多查几个城市减少网络开销。异常处理不能马虎。第三方服务说不准什么时候就出问题熔断、降级、超时控制这些机制都得配上。就算气象API完全不可用我们至少还能返回缓存里的旧数据或者给个默认值不至于让整个页面卡住。监控也得跟上。成功率、响应时间、缓存命中率这些指标要实时看着有问题早发现早处理。实际做下来这套方案在我们生产环境跑了一年多一直挺稳定的。天气服务的可用性做到了99.9%以上平均响应时间在100毫秒以内业务方反馈也不错。如果你也在做类似的功能可以参考这个思路根据你们的实际情况调整调整。获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。
