API接口设计

RESTful API 设计草案，服务于第三方应用集成。

---

基础信息

项目	内容
协议	HTTPS
格式	JSON
编码	UTF-8
版本	v1 (路径级版本控制)
文档	OpenAPI 3.0 / Swagger

---

通用约定

响应格式

{
  "status": "success",
  "data": { ... },
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 64
  },
  "links": {
    "self": "/api/v1/hexagrams/1",
    "related": "/api/v1/graph?from=hexagram-001&depth=2"
  }
}

错误格式

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "卦象 hexagram-065 不存在"
}

通用参数

参数	类型	默认值	说明
page	int	1	页码
page_size	int	20	每页数量(max 100)
lang	string	zh	语言 (zh-CN / en / zh-Hant)
fields	string	-	返回字段过滤 (逗号分隔)
sort	string	id	排序字段
order	string	asc	排序方向 (asc/desc)

---

端点列表

1. 六十四卦 - /api/v1/hexagrams

GET /api/v1/hexagrams

获取六十四卦列表。

参数	类型	说明
trigram_upper	string	按上卦过滤 (乾/坤/…)
trigram_lower	string	按下卦过滤
wuxing	string	按五行过滤 (金/木/水/火/土)
direction	string	按方位过滤
keyword	string	按关键词搜索
q	string	全文检索

GET /api/v1/hexagrams/{id}

获取单卦详情。

GET /api/v1/hexagrams/{id}/variants

获取卦变信息 (综卦、错卦、互卦)。

GET /api/v1/hexagrams/{id}/comments

获取历代注疏。

---

2. 八卦 - /api/v1/trigrams

GET /api/v1/trigrams

获取八卦列表。

GET /api/v1/trigrams/{id}

获取单卦详情。

GET /api/v1/trigrams/{id}/hexagrams

获取属于该八卦卦宫的所有六十四卦。

---

3. 概念 - /api/v1/concepts

GET /api/v1/concepts

获取概念列表。

参数	类型	说明
category	string	按分类过滤 (理论基础/术数/哲学)
depth	int	概念树层级 (用于上位/下位概念展开)

GET /api/v1/concepts/{id}

获取概念详情 (含经典原文引用)。

GET /api/v1/concepts/{id}/tree?direction=up

获取概念层级关系树。

---

4. 经典典籍 - /api/v1/classics

GET /api/v1/classics

获取典籍列表。

参数	类型	说明
dynasty	string	按朝代过滤
school	string	按学派过滤 (象数派/义理派/…)
author	string	按作者过滤

GET /api/v1/classics/{id}

获取典籍详情 (含篇章结构)。

GET /api/v1/classics/{id}/content

获取典籍内容 (分页)。

GET /api/v1/classics/{id}/references

获取引用该典籍的所有实体。

---

5. 人物 - /api/v1/persons

GET /api/v1/persons

获取人物列表。

GET /api/v1/persons/{id}

获取人物详情。

GET /api/v1/persons/{id}/lineage?type=teacher

获取师承谱系。

GET /api/v1/persons/{id}/works

获取人物著作。

---

6. 术数 - /api/v1/methods

GET /api/v1/methods

获取术数列表。

参数	类型	说明
type	string	按类型过滤 (占卜/风水/命理/…)

GET /api/v1/methods/{id}

获取术数详情 (含操作步骤)。

---

7. 知识图谱 - /api/v1/graph

GET /api/v1/graph

知识图谱查询接口。

参数	类型	必需	说明
from	string	*	起始节点 ID
to	string		目标节点 ID (最短路径查询)
depth	int		遍历深度 (默认 2, max 5)
relation	string		关系类型过滤
node_type	string		节点类型过滤 (concept/hexagram/person/…)

GET /api/v1/graph/neighbors?id={id}&depth=2

获取某节点的邻域图。

---

8. 搜索 - /api/v1/search

GET /api/v1/search

参数	类型	说明
q	string	搜索关键词
scope	string	搜索范围 (all/hexagrams/concepts/classics/persons)
lang	string	搜索语言
fuzzy	bool	是否模糊搜索 (默认 true)

---

9. 日历 - /api/v1/calendar

GET /api/v1/calendar/solar-terms

获取二十四节气列表。

GET /api/v1/calendar/sexagenary?date=2026-05-06

获取指定日期的干支纪日/纪月/纪年信息。

---

数据格式

Hexagram 响应示例

{
  "id": "hexagram-001",
  "name": "乾卦",
  "symbol": "䷀",
  "order": 1,
  "upper_trigram": { "id": "trigram-001", "name": "乾", "symbol": "☰" },
  "lower_trigram": { "id": "trigram-001", "name": "乾", "symbol": "☰" },
  "gua_ci": "元亨利贞",
  "tuan_ci": "大哉乾元...",
  "xiang_ci": "天行健，君子以自强不息",
  "yao_ci": [
    { "position": 1, "text": "潜龙勿用", "commentary": "..." },
    { "position": 2, "text": "见龙在田", "commentary": "..." }
  ],
  "wuxing": "金",
  "direction": "西北",
  "keywords": ["天", "刚健", "元亨利贞", "龙"],
  "variants": {
    "reverse": { "id": "hexagram-001", "name": "乾卦" },
    "complementary": { "id": "hexagram-002", "name": "坤卦" }
  },
  "sources": [
    {
      "title": "周易·上经",
      "url": "https://ctext.org/book-of-changes/qian1/zh",
      "dynasty": "西周"
    }
  ],
  "links": {
    "self": "/api/v1/hexagrams/hexagram-001",
    "comments": "/api/v1/hexagrams/hexagram-001/comments",
    "graph": "/api/v1/graph?from=hexagram-001&depth=2"
  }
}

---

认证与限流

项目	方案
认证	API Key (X-API-Key header)
免费额度	1000 req/day
限流	100 req/min per IP
跨域	CORS 开放 (配置白名单)

---

SDK 计划

• JavaScript/TypeScript SDK (@iching/sdk)
• Python SDK (iching-sdk)
• 微信小程序 SDK