# 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());
}
```

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.infoway.io/sdk-and-tools/java-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.