> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/sdk-and-tools/java-sdk.md).

# Java SDK

### 概述

Infoway 官方 Java SDK，采用 Builder 模式设计，提供 REST API 和 WebSocket 实时推送接口。

| 项目            | 说明                                                                                 |
| ------------- | ---------------------------------------------------------------------------------- |
| Maven Central | [`io.infoway:infoway-sdk`](https://repo1.maven.org/maven2/io/infoway/infoway-sdk/) |
| Java 版本       | 17+                                                                                |
| 依赖            | OkHttp 4.x、Gson、SLF4J                                                              |
| 协议            | MIT                                                                                |
| GitHub        | [infoway-api/infoway-sdk-java](https://github.com/infoway-api/infoway-sdk-java)    |

### 安装

#### Maven

```xml
<dependency>
    <groupId>io.infoway</groupId>
    <artifactId>infoway-sdk</artifactId>
    <version>0.1.0</version>
</dependency>
```

#### Gradle

```groovy
implementation 'io.infoway:infoway-sdk:0.1.0'
```

### 快速开始

```java
import io.infoway.sdk.InfowayClient;
import io.infoway.sdk.KlineType;
import com.google.gson.JsonElement;

// 创建客户端
InfowayClient client = InfowayClient.builder()
    .apiKey("YOUR_API_KEY")
    .build();

// 实时行情
JsonElement trades = client.stock().getTrade("AAPL.US");

// 加密货币K线
JsonElement klines = client.crypto().getKline("BTCUSDT", KlineType.DAY, 100);

// 市场温度
JsonElement temp = client.market().getTemperature("HK,US");

// 行业板块
JsonElement industry = client.plate().getIndustry("HK", 10);

// 公司概览
JsonElement company = client.stockInfo().getCompany("AAPL.US");

// 关闭客户端
client.close();
```

### 配置

| Builder 方法      | 默认值                       | 说明      |
| --------------- | ------------------------- | ------- |
| `apiKey(key)`   | 环境变量 `INFOWAY_API_KEY`    | API 密钥  |
| `baseUrl(url)`  | `https://data.infoway.io` | 基础 URL  |
| `timeout(secs)` | `15`                      | 请求超时（秒） |
| `maxRetries(n)` | `3`                       | 最大重试次数  |

### REST API 客户端

#### 行情数据（stock / crypto / japan / india / common）

| 方法                             | 说明     |
| ------------------------------ | ------ |
| `getTrade(codes)`              | 实时成交数据 |
| `getDepth(codes)`              | 买卖盘口深度 |
| `getKline(codes, type, count)` | K线数据   |

#### 基础信息

```java
client.basic().getSymbols("US");                    // 品种列表
client.basic().getSymbolInfo("AAPL.US");            // 品种详情
client.basic().getTradingDays("US");                // 交易日历
client.basic().getTradingHours("US");               // 交易时间
client.basic().getAdjustmentFactors("AAPL.US");     // 复权因子
```

#### 市场概览

```java
client.market().getTemperature("HK,US");   // 市场温度
client.market().getBreadth("US");          // 涨跌统计
client.market().getIndexes();              // 全球指数
client.market().getLeaders("US", 10);      // 领涨行业
client.market().getRankConfig("US");       // 排行榜配置
```

#### 板块分析

```java
client.plate().getIndustry("HK", 200);              // 行业板块列表
client.plate().getConcept("HK", 100);               // 概念板块列表
client.plate().getMembers("IN20293.HK", 0, 50);     // 板块成分股
client.plate().getIntro("IN20293.HK");              // 行业介绍
client.plate().getChart("HK", 50);                  // 板块热力图
```

#### 个股基本面

```java
client.stockInfo().getValuation("AAPL.US");  // 估值数据
client.stockInfo().getRatings("AAPL.US");    // 机构评级
client.stockInfo().getCompany("AAPL.US");    // 公司概览
client.stockInfo().getPanorama("AAPL.US");    // 全景数据
client.stockInfo().getConcepts("AAPL.US");    // 概念标签
client.stockInfo().getEvents("AAPL.US", 20);  // 公司大事
client.stockInfo().getDrivers("AAPL.US");     // 关键驱动
```

### WebSocket 实时推送

```java
import io.infoway.sdk.InfowayWebSocket;

InfowayWebSocket ws = InfowayWebSocket.builder()
    .apiKey("YOUR_API_KEY")
    .business("stock")
    .onTrade(msg -> System.out.println("成交: " + msg))
    .onDepth(msg -> System.out.println("盘口: " + msg))
    .onKline(msg -> System.out.println("K线: " + msg))
    .onError(err -> System.err.println("错误: " + err.getMessage()))
    .onReconnect(() -> System.out.println("已重连"))
    .build();

ws.connect();
ws.subscribeTrade("AAPL.US,TSLA.US");
ws.subscribeDepth("AAPL.US");

// 取消订阅
ws.unsubscribeTrade("TSLA.US");
// 关闭连接
ws.close();
```

### K线类型

| 枚举值          | 周期   |
| ------------ | ---- |
| MIN\_1 (1)   | 1分钟  |
| MIN\_5 (2)   | 5分钟  |
| MIN\_15 (3)  | 15分钟 |
| MIN\_30 (4)  | 30分钟 |
| HOUR\_1 (5)  | 1小时  |
| HOUR\_2 (6)  | 2小时  |
| HOUR\_4 (7)  | 4小时  |
| DAY (8)      | 日线   |
| WEEK (9)     | 周线   |
| MONTH (10)   | 月线   |
| QUARTER (11) | 季线   |
| YEAR (12)    | 年线   |

### 错误处理

```java
import io.infoway.sdk.exception.*;

try {
    client.stock().getTrade("AAPL.US");
} catch (InfowayAuthException e) {
    System.err.println("认证失败: " + e.getMsg());
} catch (InfowayApiException e) {
    System.err.println("API 错误 [" + e.getRet() + "]: " + e.getMsg());
    System.err.println("Trace ID: " + e.getTraceId());
} catch (InfowayTimeoutException e) {
    System.err.println("请求超时: " + e.getMessage());
}
```

***