Java初学者项目实战：实现一个基础的股票查询工具

选用 OkHttpClient 而非 HttpURLConnection，因其支持连接池、统一超时配置、明确错误提示；推荐 Gson 解析 JSON，配合 @SerializedName 和 BigDecimal；中文股票名通过本地 CSV 映射；网络请求须在子线程执行。

为什么不用 HttpURLConnection 而选 OkHttpClient？

初学者常从 HttpURLConnection 入手，但它默认不支持连接池、超时配置分散、JSON 解析要手动拼接字符串——写完一个请求就容易卡在

InputStream 关闭或中文乱码上。用 OkHttpClient 更贴近实际项目习惯，且错误提示更明确（比如直接告诉你 java.net.SocketTimeoutException 是哪次请求超时）。

实操建议：

• 用 Maven 引入 com.squareup.okhttp3:okhttp:4.12.0（别用 3.x，API 差异大）
• 全局复用同一个 OkHttpClient 实例，避免创建过多 socket
• 务必设置 connectTimeout 和 readTimeout，否则网络卡住会阻塞主线程

OkHttpClient client = new OkHttpClient.Builder()
    .connectTimeout(10, TimeUnit.SECONDS)
    .readTimeout(15, TimeUnit.SECONDS)
    .build();

如何安全解析股票 API 返回的 JSON？

很多免费接口（如 Alpha Vantage、Tushare 测试环境）返回的是嵌套 JSON，字段名大小写不统一，还可能缺失某些 key。用 org.json 手动取值容易抛 JSONException；用 Jackson 又要配注解——对初学者来说，com.google.gson.Gson 最轻量。

注意点：

• 不要直接 gson.fromJson(jsonStr, StockData.class)，先检查响应体是否为空或含 "Error Message"
• 定义 Java 类时，用 @SerializedName 显式绑定字段，比如 API 返回 "50-Day Moving Average"，对应字段写 @SerializedName("50-Day Moving Average") String ma50;
• 价格类字段统一用 BigDecimal，避免 double 精度丢失（比如 19.99 + 0.01 变成 19.999999999999996）

怎么让命令行查询支持中文股票名称？

国内用户输入“贵州茅台”比输入“600519.SS”更自然，但绝大多数公开 API 只认代码。需要本地维护一份简表映射，而不是每次联网查。

推荐做法：

• 准备一个 stock_map.csv，内容如：贵州茅台,600519.SS、宁德时代,300750.SZ
• 启动时用 Files.readAllLines(Paths.get("stock_map.csv")) 加载进 Map，键为中文名，值为代码
• 用户输入后先查 map，查不到再原样当代码处理（兼容两种输入）
• 别用 Scanner.nextLine() 后直接 .trim() 就完事——Windows 换行符可能带 \r，导致匹配失败

为什么查询结果不能直接 System.out.println()？

Java 的 toString() 默认打印对象地址，新手看到 StockData@3d4eac69 容易以为没拿到数据。必须重写 toString()，或用 Gson 格式化输出。

更关键的是：真实行情有延迟，免费接口通常只返回日线，且无实时买卖盘口。如果用户期待“像炒股软件一样刷新”，得提前说明限制，否则调试时反复改代码也得不到想要的效果。

最容易被忽略的一点：所有网络调用必须放在子线程里（哪怕只是 new Thread(() -> {...}).start()），否则 Swing 或 JavaFX 界面会冻结，命令行程序在 Windows 上也可能卡住输入光标。