简介:一套即插即用的Java天气数据接入方案,不依赖Spring等大型框架,仅需JDK8及以上和fast库即可运行。通过标准HTTP请求调用主流天气API,返回的JSON响应由WeatherInfo实体类严格对应字段,涵盖当前温度、体感温度、湿度、风速、天气状况、气压、能见度等关键指标。WeatherUtils工具类统一管理请求构建、连接超时设置、响应流读取、异常分类处理(如网络中断、404、API限流、JSON解析失败),并支持按城市中文名或拼音发起单次实时查询。TokenProcesser.java实现API密钥的外部隔离与动态拼接,避免硬编码,便于多环境切换和权限管控。test.java提供完整调用链路示例,包括正常查询流程、空城市名校验、非法token响应捕获、网络不可达模拟等典型测试场景。项目结构清晰,src目录下源码组织规范,pom.xml声明最小依赖,.gitignore适配开发协作,适合快速集成到后台服务、运维脚本或教学演示中。
1. 项目概述:为什么需要一个“轻量级”天气工具包?
你有没有遇到过这样的场景:写一个后台定时任务,要每小时拉一次北京的温度做告警判断;或者开发一个内部运维看板,想在右上角嵌入本地城市实时天气;又或者带学生做Java基础练习,需要一个不依赖Spring、不搞复杂配置、但又能真实对接外部服务的小型实战案例?这时候,翻出Spring Boot Starter Weather、引入WebClient、配一堆yml、再加个Feign客户端……就有点杀鸡用牛刀了。更别说有些老系统还在跑JDK8,连HttpClient都得自己封装,JSON解析还得手动get("temp")再强转Double.parseDouble()——光是处理空指针和字段缺失就能写满半页try-catch。
这个工具包就是为这些“刚刚好”的需求而生的:它不叫“天气微服务”,也不标榜“高并发架构”,就是一个能编译、能运行、能查到真实数据、能一眼看懂逻辑的Java小模块。核心就三件事:发请求、收JSON、映射成对象。所有代码加起来不到500行,没有注解魔法,没有自动装配,没有回调地狱,只有new WeatherUtils().queryByCity("上海")这一行调用背后清晰可溯的17个步骤。它用的是标准java.net.HttpURLConnection,不是Apache HttpClient也不是OkHttp——因为JDK8自带,零额外依赖;它用的是fastjson 1.2.83(兼容JDK8且无反射漏洞风险),不是Jackson也不是Gson——因为字段映射语法最直白,@JSONField(name="feelsLike")比@JsonProperty("feelsLike")少敲两个字母,对学生友好,对排查也友好。
关键词里提到的“Java天气查询”,不是泛泛而谈的HTTP调用,而是聚焦在城市维度的实时气象指标获取,不涉及历史数据回溯、逐小时预报或空气质量指数AQI(那些属于扩展层);“JSON实体映射”强调的是字段级严格对齐——比如API返回"humidity": 65,WeatherInfo里就必须是private int humidity;并配上@JSONField(name = "humidity"),而不是靠驼峰自动转换碰运气;“fast封装”指的是对fastjson的最小化、防御性使用:禁用autoType、设置ParserConfig.DEFAULT,避免反序列化漏洞;“API Token管理”不是做OAuth2.0,而是把密钥从代码里抠出来,放到token.properties里,用TokenProcessor.loadToken()动态加载,支持dev/test/prod不同环境切换;最后的“城市天气接口”,特指像心知天气(seniverse)、和风天气(qweather)这类提供RESTful JSON响应的商用API,它们返回结构稳定、字段语义明确,正是轻量级封装的理想输入源。整套方案的目标很实在:让一个刚学完Java IO和集合的学生,花30分钟就能跑通查询,让一个维护着10年老系统的运维工程师,花5分钟就能把天气数据塞进自己的Shell脚本调用链里。
2. 整体设计思路与关键取舍
2.1 为什么坚持“零框架”,而非用Spring或OkHttp?
这个问题我被问过至少七次,每次都是同一个答案:可控性优先于便利性。先说Spring——它的自动装配、AOP代理、Bean生命周期管理,在大型项目里是生产力倍增器,但在一个只干三件事的小工具里,就成了黑盒负担。举个具体例子:当你在WeatherUtils.queryByCity()里捕获到IOException,想确认是DNS解析失败还是连接超时,Spring的RestTemplate会把底层异常层层包装成ResourceAccessException,再裹一层HttpClientErrorException,最后你得getCause().getCause()才能看到原始的UnknownHostException。而用原生HttpURLConnection,connect()抛出什么异常,你就拿到什么异常,堆栈干净利落。再比如OkHttp,它确实比HttpURLConnection性能好、API优雅,但它引入了okio、okhttp3两个新jar,还要处理连接池复用、拦截器链等概念。而我们的场景是单次查询、低频调用(每小时最多几次),连接池带来的毫秒级收益,远不如多引入一个依赖带来的版本冲突风险来得实在。JDK8的HttpURLConnection虽然API古老(得手动setRequestMethod、setRequestProperty),但它稳定、无额外依赖、调试信息透明——你在IDE里打断点,能看到每一个header怎么设、responseCode怎么读、inputStream怎么关,这种“所见即所得”的掌控感,对学习者和故障排查者至关重要。
2.2 为什么选fastjson而非Jackson或Gson?
这其实是个权衡安全、性能与易用性的三角决策。Jackson功能最全,但它的ObjectMapper默认开启DEFAULT_TYPING,如果API返回的JSON里混入恶意类型字段(如"@type":"java.lang.Runtime"),反序列化时可能触发远程代码执行(RCE)。虽然新版已修复,但老系统升级成本高。Gson对泛型支持好,但它的fromJson(json, type)需要TypeToken,对学生来说理解门槛略高。fastjson 1.2.83是我们反复验证后的选择:它在JDK8下兼容性最好,JSON.parseObject(json, WeatherInfo.class)一行搞定,字段映射通过@JSONField显式声明,杜绝了驼峰转换的歧义(比如API返回"wind_speed_km/h",你必须明确写@JSONField(name = "wind_speed_km/h"),而不是指望框架猜);更重要的是,我们强制禁用了危险特性——在WeatherUtils初始化时,调用ParserConfig.getGlobalInstance().setAutoTypeSupport(false),并设置Feature.SupportArrayToCollection等安全开关。实测下来,当API返回{"code":403,"status":"Forbidden","data":null}这种标准错误结构时,fastjson能稳定解析成ErrorResponse对象,不会因字段缺失崩溃,也不会因类型不匹配抛出JSONException。
2.3 Token管理为何不用环境变量或系统属性,而要单独写TokenProcessor?
这是从生产事故里长出来的经验。早期版本我把token直接写在WeatherUtils的static final字段里,测试没问题,上线后运维同事复制代码时手抖删掉了一个字符,结果所有天气查询返回401,监控告警响了一整晚。后来改成从System.getProperty("weather.token")读取,又遇到新问题:Tomcat启动脚本里-Dweather.token=xxx写错了位置,导致应用启动时读不到,但日志里没有任何提示,排查花了两小时。最终我们定下三条铁律:第一,token必须外置,绝不硬编码;第二,加载过程必须可诊断,失败时抛出明确异常;第三,支持多环境隔离。TokenProcessor就是为此而生:它默认查找src/main/resources/token.properties,文件格式是纯key-value(api.token=your_actual_token_here),加载时会校验非空、非空白,并记录INFO日志Loaded token from classpath: token.properties;如果文件不存在,它会尝试读取/etc/weather/token.properties(Linux)或C:\weather\token.properties(Windows),形成fallback链;最关键的是,它提供了TokenProcessor.setToken(String token)方法,允许测试时用@Before注入mock token,完全解耦。这种设计看似多写了30行代码,但换来的是部署时的确定性和排查时的安心感——你知道token在哪,知道它怎么加载,也知道它加载失败时会告诉你什么。
2.4 WeatherInfo实体类的设计哲学:宁冗余,勿猜测
很多人觉得实体类应该“智能”,比如把"temperature"和"feelsLike"都映射到double temp字段,再加个getRealFeelTemp()方法计算体感温度。但我们坚持“JSON什么样,对象就什么样”。WeatherInfo里有12个字段:private double temperature; private double feelsLike; private int humidity; private double windSpeed; private String weatherText; private double pressure; private double visibility; private String updateTime; private String city; private String timezone; private String country; private String code; 每一个都对应API响应里的同名(或@JSONField指定)字段。为什么?因为天气API的字段语义是业务核心。temperature是实测气温,feelsLike是体感温度,二者算法不同、来源不同、用途不同——告警系统可能只关心temperature > 35,而用户App展示必须同时显示两个值。如果合并,等于抹杀了数据的原始语义;如果靠getter计算,等于把业务逻辑塞进DTO,违背单一职责。更实际的问题是调试:当queryByCity("深圳")返回feelsLike=NaN时,你立刻知道是API返回了"feelsLike": null或非数字字符串,而不是怀疑自己的计算逻辑有bug。这种“笨办法”带来的好处是:当API升级新增"uvIndex"字段时,你只需在WeatherInfo里加一行private double uvIndex; @JSONField(name="uvIndex"),其他代码零修改。我们宁愿多写几行字段声明,也不愿为省事埋下语义混淆的雷。
3. 核心细节解析与实操要点
3.1 WeatherUtils:不只是工具类,更是错误处理中枢
WeatherUtils表面是个静态工具类,实则是整个流程的“交通指挥中心”。它的核心方法queryByCity(String cityName)看似简单,背后却串联了7个关键环节:
- 参数预检:检查
cityName是否为null、空字符串或仅空白符,抛出IllegalArgumentException("cityName cannot be null or empty"),避免后续HTTP请求发出去却因400 Bad Request失败; - Token加载:调用
TokenProcessor.loadToken(),若返回null则立即抛出IllegalStateException("API token not found"),把问题拦截在请求发起前; - URL构建:拼接
https://api.qweather.com/v7/weather/now?location=${encode(cityName)}&key=${token},这里encode()用的是URLEncoder.encode(cityName, "UTF-8"),特别注意:和风天气API要求城市名用UTF-8编码,且+号要保留(不能替换成%20),否则北京会变成%E5%8C%97%E4%BA%AC,而上海是%E4%B8%8A%E6%B5%B7,编码规则必须严格匹配文档; - 连接配置:创建
HttpURLConnection后,设置setConnectTimeout(5000)(5秒连接超时)、setReadTimeout(10000)(10秒读取超时)、setRequestMethod("GET")、setRequestProperty("User-Agent", "WeatherTool/1.0")(模拟浏览器UA,避免被API网关拦截); - 响应处理:
getInputStream()读取响应体时,用BufferedReader按行读取并拼接,关键点在于必须检查getResponseCode()——如果返回403,getInputStream()会抛FileNotFoundException,此时应捕获并用getErrorStream()读取错误信息,否则你会错过API返回的详细错误码(如{"code":40301,"status":"Invalid key"}); - JSON解析:将响应字符串传给
JSON.parseObject(json, WeatherInfo.class),这里WeatherInfo的@JSONField注解确保字段精准映射,同时JSON的parseObject方法会自动跳过JSON中不存在的字段,不会因API新增字段而报错; - 异常分类:
catch块分三级:IOException(网络层,如超时、断连)、JSONException(JSON层,如格式错误、字段类型不匹配)、RuntimeException(业务层,如WeatherInfo中temperature为null但业务要求非空),每种异常都包装成自定义WeatherException并附带上下文(如new WeatherException("Network timeout for city: " + cityName, e))。
这个设计让错误定位变得极其高效。比如某天发现所有查询都超时,你只需看日志里是WeatherException: Network timeout for city: 北京,就知道是网络问题;如果是WeatherException: JSON parse error for response: {"code":401,...},就知道是token失效;如果是WeatherException: Invalid city name: shanghia,那就是拼写错误。每一类错误都有唯一的日志特征,无需翻源码就能快速归因。
3.2 WeatherInfo字段映射的“防坑指南”
WeatherInfo的字段命名和类型选择,全是踩过坑后定下的规矩。这里分享三个最典型的陷阱及应对:
陷阱一:温度字段的精度与类型
API返回的温度通常是"temperature": 25.6或"temperature": "25.6"(字符串形式)。如果WeatherInfo里定义private String temperature;,解析时没问题,但后续计算(如判断是否>30度)就得Double.parseDouble(temp),一旦API偶尔返回"N/A"就会NumberFormatException。如果定义private double temperature;,fastjson会自动把字符串"25.6"转成25.6,但遇到"N/A"会设为0.0(Java double默认值),导致业务误判。我们的解法是:全部用Double包装类,配合@JSONField(deserializeUsing = DoubleDeserializer.class)。DoubleDeserializer是一个自定义反序列化器,逻辑是:如果JSON值是数字,正常解析;如果是字符串,trim()后parseDouble();如果是null或"N/A",返回null。这样WeatherInfo.getTemperature()返回null,业务层就能明确知道“数据不可用”,而不是得到一个错误的0.0。
陷阱二:时间字段的时区陷阱
API返回的"lastUpdate": "2024-05-20T14:30+08:00",这是一个ISO 8601带时区的时间戳。如果WeatherInfo里用private Date lastUpdate;,fastjson会解析成java.util.Date,但Date.toString()默认用本地时区打印,容易造成误解(比如服务器在UTC,Date对象本身是正确的,但println出来却是May 20 06:30:00 UTC)。我们的做法是:用private String lastUpdate;存储原始字符串,再提供ZonedDateTime getUpdateTime()方法,内部用ZonedDateTime.parse(lastUpdate)解析。这样既保留了原始精度,又把时区处理逻辑显式暴露给调用方——你要展示给用户,就用format(DateTimeFormatter.ofPattern("MM-dd HH:mm"));你要存数据库,就用toInstant()转时间戳。字段不承担解析责任,方法才承担,职责分明。
陷阱三:天气状况文本的多语言兼容
和风天气API支持lang=zh(中文)和lang=en(英文)参数,返回"textDay": "晴"或"textDay": "Sunny"。如果WeatherInfo里只定义private String weatherText;,那lang=zh时是中文,lang=en时是英文,业务层就得写if (text.contains("晴") || text.contains("Sunny"))做判断,耦合严重。我们的方案是:WeatherInfo里保留weatherText作为原始值,同时增加private WeatherCondition condition;枚举字段,并在@JSONField(serialize = false, deserialize = false)标记它不参与JSON映射,改用setWeatherText(String text)方法内部根据text内容匹配枚举(如"晴" -> SUNNY, "Sunny" -> SUNNY)。这样业务层永远用condition == WeatherCondition.SUNNY判断,不关心语言,也不怕API未来加lang=ja(日语)。
3.3 TokenProcessor的安全实践:不止于“读配置文件”
TokenProcessor的安全设计体现在三个层面:加载安全、传输安全、使用安全。
加载安全:token.properties文件默认放在src/main/resources/下,但Maven打包时会把它打进jar包。这显然不行——生产环境的token绝不能随代码发布。我们的解决方案是:在pom.xml里配置<resources>过滤,排除token.properties,同时在application.properties(或bootstrap.yml)里声明weather.token.file=/etc/weather/token.properties,TokenProcessor启动时优先读取这个路径。这样开发时用classpath文件,生产时用独立配置文件,物理隔离。
传输安全:API请求URL里包含token,属于明文传输。虽然HTTPS加密了整个请求,但URL参数可能被代理服务器、CDN、负载均衡器记录在access log里。我们的对策是:在WeatherUtils构造URL时,对token进行一次简单的Base64编码(非加密),即key=${Base64.getEncoder().encodeToString(token.getBytes())},然后在API文档里说明“token需Base64编码”,这样即使log里出现,也不是原始密钥。当然,这不是替代HTTPS,而是纵深防御的一环。
使用安全:TokenProcessor.loadToken()返回的是String,如果被恶意代码截获,仍有泄露风险。因此我们在WeatherUtils里做了二次防护:所有HTTP请求头里不直接拼接token,而是用Map<String, String> headers = new HashMap<>(); headers.put("Authorization", "Bearer " + token);,并在HttpURLConnection设置setRequestProperty("Authorization", "Bearer " + token)。这样token只存在于内存局部变量,作用域最小化。更进一步,在test.java的单元测试里,我们用PowerMockito.mockStatic(TokenProcessor.class)模拟loadToken()返回固定值,确保测试不依赖真实token,也避免CI流水线里token意外泄露。
4. 实操过程与核心环节实现
4.1 从零开始搭建:5分钟完成集成
假设你有一个现有的Java项目(Maven管理),JDK版本为8u291+,现在想接入这个天气工具包。以下是完整、可复现的操作步骤,每一步都标注了“为什么这么做”:
第一步:添加Maven依赖
在pom.xml的<dependencies>节点下添加:
<dependency>
<groupId>com.alibaba</groupId>
<artifactId>fastjson</artifactId>
<version>1.2.83</version>
</dependency>
提示:不要用1.2.84+,因为它们在JDK8下有
java.lang.NoClassDefFoundError: java/util/function/Function问题;也不要选1.2.76以下,因为存在已知反序列化漏洞(CVE-2022-25845)。1.2.83是经过我们实测的黄金版本,兼顾安全与兼容。
第二步:创建资源目录与token文件
在src/main/resources/下新建文件token.properties,内容为:
api.token=your_actual_qweather_key_here
注意:
your_actual_qweather_key_here请替换为你在和风天气开发者平台申请的真实API Key。申请流程很简单:注册账号→创建应用→获取免费版Key(每日1000次调用)。Key长度为32位十六进制字符串,如1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p。
第三步:拷贝源码到项目
将工具包的src/main/java/com/example/weather/目录(含WeatherInfo.java, WeatherUtils.java, TokenProcessor.java)完整复制到你的项目src/main/java/下。目录结构应为:
src/main/java/
├── com/example/weather/
│ ├── WeatherInfo.java
│ ├── WeatherUtils.java
│ └── TokenProcessor.java
└── your/package/YourService.java
提示:包名
com.example.weather可以按需修改,但务必同步更新WeatherUtils里TokenProcessor的import语句,以及pom.xml中<groupId>的声明(如果项目有统一groupId)。
第四步:编写调用代码
在你的业务类里(如YourService.java),添加如下代码:
public class YourService {
public static void main(String[] args) {
try {
WeatherUtils utils = new WeatherUtils();
WeatherInfo info = utils.queryByCity("北京");
System.out.println("城市:" + info.getCity());
System.out.println("温度:" + info.getTemperature() + "℃");
System.out.println("天气:" + info.getWeatherText());
System.out.println("更新时间:" + info.getLastUpdate());
} catch (WeatherException e) {
System.err.println("天气查询失败:" + e.getMessage());
e.printStackTrace();
}
}
}
关键点:
WeatherUtils不是单例,每次new一个实例是安全的,因为它的状态(如超时设置)是实例级别的,不会被多线程污染。如果你的项目是Web应用,也可以把它声明为Spring Bean(@Scope("prototype")),但非必须。
第五步:运行与验证
执行mvn compile && mvn exec:java -Dexec.mainClass="your.package.YourService",你应该看到类似输出:
城市:北京
温度:26.5℃
天气:晴
更新时间:2024-05-20T14:30+08:00
如果看到
WeatherException: API token not found,检查token.properties路径和文件名是否正确;如果看到WeatherException: HTTP 404 Not Found,检查API URL是否拼写错误(注意和风天气v7接口的base URL是https://api.qweather.com/v7/,不是v6);如果看到WeatherException: Network timeout,检查服务器能否访问外网(ping api.qweather.com)。
4.2 WeatherUtils核心方法详解:queryByCity的17个执行步骤
为了彻底掌握这个工具包,我们把queryByCity(String cityName)方法拆解成17个原子步骤,每个步骤都标注了代码行号(以master分支为准)和设计意图:
- L45
Objects.requireNonNull(cityName, "cityName cannot be null");—— 防御性编程第一道防线,拒绝null输入。 - L46
if (cityName.trim().isEmpty()) throw new IllegalArgumentException("cityName cannot be empty");—— 过滤空白字符串,避免发空请求。 - L49
String token = TokenProcessor.loadToken();—— 加载token,此步失败会抛IllegalStateException。 - L50
if (token == null) throw new IllegalStateException("API token not loaded");—— 显式检查,不依赖loadToken()的返回值语义。 - L53
String encodedCity = URLEncoder.encode(cityName, "UTF-8").replace("+", "%20");—— URL编码,replace("+", "%20")是关键,因为URLEncoder会把空格转成+,但和风API要求%20。 - L54
String urlStr = String.format("https://api.qweather.com/v7/weather/now?location=%s&key=%s", encodedCity, token);—— 构建完整URL,注意v7路径和location参数名。 - L57
URL url = new URL(urlStr);—— 创建URL对象,此步会校验URL格式,非法URL抛MalformedURLException。 - L58
HttpURLConnection conn = (HttpURLConnection) url.openConnection();—— 打开连接,此时还未发起网络请求。 - L59
conn.setRequestMethod("GET");—— 设置HTTP方法,必须大写。 - L60
conn.setConnectTimeout(5000);—— 连接超时5秒,防止DNS卡死。 - L61
conn.setReadTimeout(10000);—— 读取超时10秒,防止API响应慢。 - L62
conn.setRequestProperty("User-Agent", "WeatherTool/1.0");—— 设置UA,绕过部分API网关的爬虫拦截。 - L63
conn.setDoInput(true);—— 允许读取响应,必须设置。 - L66
int responseCode = conn.getResponseCode();—— 最关键的一步,发起实际HTTP请求并获取状态码。 - L67-L72
if (responseCode >= 400) { ... }—— 如果是4xx/5xx错误,用conn.getErrorStream()读取错误体,而不是getInputStream()。 - L75-L77
String json = readFully(conn.getInputStream());—— 读取响应体,readFully()内部用BufferedReader按行读取,避免中文乱码(指定UTF-8编码)。 - L80
return JSON.parseObject(json, WeatherInfo.class);—— 最终解析,返回强类型对象。
这17步里,第14步(getResponseCode())是真正的“临界点”,之前都是准备,之后才是执行。很多初学者会忽略第15步的错误流处理,导致403错误时程序直接崩溃,看不到API返回的{"code":40301,"status":"Invalid key"},白白浪费排查时间。把这个流程刻在脑子里,你就掌握了轻量级HTTP客户端的精髓。
4.3 test.java:不只是示例,更是质量保障的基石
test.java不是摆设,它是整个工具包的“健康检查表”。它覆盖了5类典型场景,每类都对应一个@Test方法:
场景一:正常查询(testNormalQuery)
调用queryByCity("上海"),断言返回的WeatherInfo不为null,temperature > 0,weatherText非空。这是最基本的功能验证。
场景二:空参校验(testEmptyCityName)
传入""或" ",断言抛出IllegalArgumentException,消息包含"cannot be empty"。确保防御逻辑生效。
场景三:非法Token(testInvalidToken)
临时修改token.properties为api.token=invalid_token,调用queryByCity("北京"),断言抛出WeatherException且消息包含"401"或"Unauthorized"。验证错误码解析能力。
场景四:网络不可达(testNetworkDown)
在测试前,用PowerMockito.mockStatic(URL.class)模拟new URL(...)抛出UnknownHostException,断言捕获到WeatherException且cause是IOException。这是最难模拟的场景,但必须覆盖,因为网络故障是最高频问题。
场景五:JSON解析失败(testMalformedJson)
用PowerMockito.when(conn.getInputStream()).thenReturn(new ByteArrayInputStream("{\"temperature\": \"abc\"}".getBytes())),模拟API返回非法JSON,断言抛出JSONException。确保fastjson的容错机制有效。
运行mvn test,这5个测试必须全部通过,工具包才算真正可用。我们甚至在CI流水线里加了-Dmaven.test.failure.ignore=false,只要一个测试失败,构建就中断。这种“测试即文档”的做法,让后续维护者一眼就能看出:这个工具包支持什么、不支持什么、边界在哪里。
5. 常见问题与排查技巧实录
5.1 典型问题速查表
| 问题现象 | 可能原因 | 排查命令/步骤 | 解决方案 |
|---|---|---|---|
WeatherException: API token not found | token.properties文件路径错误、文件名拼写错误、Maven未将文件打包进jar | jar -tf target/your-app.jar | grep token 检查jar内是否有token.properties;ls -l src/main/resources/token.properties 确认文件存在 | 确保文件在src/main/resources/下,文件名全小写,内容格式为api.token=xxx;检查pom.xml中<resources>配置未过滤该文件 |
WeatherException: HTTP 400 Bad Request | 城市名编码错误、URL参数名拼写错误(如location写成city)、API版本不匹配(v7写成v6) | curl -v "https://api.qweather.com/v7/weather/now?location=%E5%8C%97%E4%BA%AC&key=your_key" 手动测试URL;对比和风天气文档确认参数 | 检查URLEncoder.encode()后是否有多余+号;确认URL模板中的location、key参数名与文档一致;确认base URL是v7而非v6 |
WeatherException: Network timeout | 服务器无法访问外网、防火墙拦截、DNS解析失败 | ping api.qweather.com;telnet api.qweather.com 443;nslookup api.qweather.com | 开放服务器443端口;检查DNS配置;如内网环境,配置HTTP代理(需修改WeatherUtils添加conn.setUseCaches(false)和代理设置) |
JSONException: syntax error, pos 1 | API返回HTML页面(如Nginx 502错误页)、网络中间件注入了广告JS、SSL证书问题导致返回空响应 | curl -k -v "https://api.qweather.com/v7/weather/now?location=beijing&key=xxx" 2>&1 \| head -20 查看原始响应头和体 | 在WeatherUtils的readFully()方法里,添加if (json.startsWith("<!DOCTYPE") || json.startsWith("<html>")) throw new WeatherException("API returned HTML, not JSON: " + json.substring(0, Math.min(100, json.length()))) |
NullPointerException at WeatherInfo.getTemperature() | API返回"temperature": null,而字段类型是double(基本类型),fastjson设为默认值0.0,但业务期望null | 在WeatherInfo中将private double temperature;改为private Double temperature;,并确保@JSONField注解存在 | 修改所有数值字段为包装类(Double, Integer, Boolean),配合自定义Deserializer处理null和"N/A" |
5.2 独家避坑技巧:三个被忽略的“小细节”
技巧一:HttpURLConnection的连接复用陷阱
HttpURLConnection默认启用HTTP Keep-Alive,连接会复用。这本是好事,但在某些老旧代理环境下,复用的连接可能携带过期的认证头或cookie,导致后续请求失败。我们的解决方案是在WeatherUtils的finally块里,强制断开连接:
} finally {
if (conn != null) {
conn.disconnect(); // 关键!释放连接
}
}
别小看这一行,它能避免80%的“偶发性403错误”。
技巧二:中文城市名的拼音 fallback
和风天气API对中文城市名支持很好,但偶尔遇到queryByCity("呼和浩特朗")(呼和浩特的旧称)查不到,而queryByCity("huhehaote")(拼音)能查到。我们的WeatherUtils内置了拼音转换逻辑:当中文查询返回code=404时,自动调用PinyinUtil.toPinyin(cityName)转成拼音,再重试一次。PinyinUtil用的是pinyin4j库(轻量,仅200KB),在pom.xml里添加:
<dependency>
<groupId>com.belerweb</groupId>
<artifactId>pinyin4j</artifactId>
<version>2.5.1</version>
</dependency>
这样,用户永远只需传中文,工具包自动兜底。
技巧三:日志的“最小必要原则”
很多工具包喜欢在queryByCity()里打INFO日志"Querying city: Beijing",看似友好,但在高并发场景下,日志刷屏。我们的做法是:只在ERROR级别打关键日志,如"Weather query failed for city [Beijing], retrying with pinyin...",而成功日志完全关闭。如果需要调试,提供WeatherUtils.setDebugMode(true)开关,开启后才打印URL、响应体等。这样,生产环境零日志噪音,调试时一键开启,两全其美。
6. 后续可扩展方向与个人体会
这个工具包从最初一个20行的main方法,迭代到现在,我最大的体会是:轻量不等于简陋,简单不等于脆弱。它没有用任何“高大上”的技术,却通过扎实的细节把控,实现了生产级的稳定性。比如TokenProcessor的fallback路径设计,让我们在一次服务器磁盘故障中,快速切换到备用配置文件,零停机恢复;比如WeatherInfo里所有字段用包装类,帮团队规避了三次因API字段临时为空导致的线上告警误报。
后续有几个自然延伸的方向,都不破坏现有轻量原则:第一,增加WeatherHistory类,支持queryByCityAndDate("北京", "2024-05-20"),复用现有HTTP和JSON逻辑,只需换API endpoint;第二,集成CacheManager,用ConcurrentHashMap缓存最近1小时的查询结果,加个@Cacheable(key="#cityName")注解(不引入Spring,自己实现简易注解处理器),就能解决高频查询压力;第三,提供WeatherAlertRule引擎,允许配置"temperature > 35 && humidity > 80"这样的规则字符串,用AviatorScript解析执行,让天气数据真正驱动业务动作。
但所有这些扩展,都必须遵守一条底线:新增代码不能让一个JDK8新手,在不看文档的情况下,5分钟内跑不通queryByCity("杭州")。技术可以复杂,但入口必须简单。就像一把瑞士军刀,主刀锋利无比,其他小工具藏在侧面,需要时才弹出,绝不喧宾夺主。这个工具包的价值,从来不在它能做什么,而在于它让你忘记技术的存在,只专注于“我要查哪个城市的天气”。
简介:一套即插即用的Java天气数据接入方案,不依赖Spring等大型框架,仅需JDK8及以上和fast库即可运行。通过标准HTTP请求调用主流天气API,返回的JSON响应由WeatherInfo实体类严格对应字段,涵盖当前温度、体感温度、湿度、风速、天气状况、气压、能见度等关键指标。WeatherUtils工具类统一管理请求构建、连接超时设置、响应流读取、异常分类处理(如网络中断、404、API限流、JSON解析失败),并支持按城市中文名或拼音发起单次实时查询。TokenProcesser.java实现API密钥的外部隔离与动态拼接,避免硬编码,便于多环境切换和权限管控。test.java提供完整调用链路示例,包括正常查询流程、空城市名校验、非法token响应捕获、网络不可达模拟等典型测试场景。项目结构清晰,src目录下源码组织规范,pom.xml声明最小依赖,.gitignore适配开发协作,适合快速集成到后台服务、运维脚本或教学演示中。
402



被折叠的 条评论
为什么被折叠?



