diff --git a/API.md b/API.md new file mode 100644 index 0000000..51e82b6 --- /dev/null +++ b/API.md @@ -0,0 +1,310 @@ +# 📡 数据可视化图表生成器 - API 文档 + +> 版本：v1.1.0 | 基础地址：`http://192.168.0.101:16023` + +--- + +## 接口总览 + +| 方法 | 路径 | 说明 | +|------|------|------| +| POST | `/api/chart` | 生成图表图片（JSON body，推荐） | +| GET | `/api/chart` | 生成图表图片（URL 参数） | +| GET | `/api/health` | 健康检查 | +| GET | `/api/docs` | 返回本文档（JSON） | + +--- + +## 1. POST /api/chart（推荐） + +通过 JSON 请求体生成图表，返回 PNG 图片。 + +### 请求 + +``` +POST /api/chart +Content-Type: application/json +``` + +### 参数说明 + +| 参数 | 类型 | 必填 | 默认值 | 说明 | +|------|------|:----:|--------|------| +| `data` | string | ✅ | — | CSV 格式数据，`\n` 换行，第一行表头，第一列横坐标 | +| `chartType` | string | — | `bar` | 图表类型：`bar` / `line` / `bar-line` | +| `title` | string | — | `""` | 图表标题 | +| `theme` | string | — | `default` | 主题风格：`default` / `dark` / `macarons` / `gradient` / `retro` | +| `showLegend` | boolean | — | `true` | 显示图例 | +| `showGrid` | boolean | — | `true` | 显示网格线 | +| `showLabel` | boolean | — | `false` | 显示数据标签 | +| `stackMode` | boolean | — | `false` | 堆叠模式 | +| `smoothLine` | boolean | — | `true` | 折线平滑 | +| `enableSplit` | boolean | — | `false` | 启用区域分割 | +| `splitIndex` | number | — | `3` | 分割位置（第几个数据后分割） | +| `leftLabel` | string | — | `"左侧"` | 左侧区域标签 | +| `rightLabel` | string | — | `"右侧"` | 右侧区域标签 | +| `splitStyle` | string | — | `"solid"` | 分割线样式：`solid` / `dashed` / `dotted` | +| `width` | number | — | `800` | 图片宽度（px） | +| `height` | number | — | `500` | 图片高度（px） | +| `pixelRatio` | number | — | `2` | 像素倍率（越大越清晰） | + +### 返回 + +- **Content-Type:** `image/png` +- **响应头:** + - `X-Chart-Width` — 图片宽度 + - `X-Chart-Height` — 图片高度 + - `X-Chart-Pixel-Ratio` — 像素倍率 + +### curl 示例 + +**基础柱状图：** +```bash +curl -X POST http://192.168.0.101:16023/api/chart \ + -H "Content-Type: application/json" \ + -d '{ + "data": "产品, Q1, Q2, Q3, Q4\n手机, 1200, 1800, 2100, 2500\n平板, 800, 950, 1100, 1300\n笔记本, 600, 750, 900, 1050", + "chartType": "bar", + "title": "季度销售对比" + }' -o chart.png +``` + +**深色主题折线图 + 数据标签：** +```bash +curl -X POST http://192.168.0.101:16023/api/chart \ + -H "Content-Type: application/json" \ + -d '{ + "data": "月份, 营收(万), 利润(万), 用户(千)\n1月, 500, 80, 50\n2月, 680, 120, 85\n3月, 820, 160, 130\n4月, 1050, 230, 200\n5月, 1380, 350, 320", + "chartType": "line", + "title": "年度增长趋势", + "theme": "dark", + "showLabel": true, + "width": 900, + "height": 500 + }' -o trend.png +``` + +**区域分割对比图：** +```bash +curl -X POST http://192.168.0.101:16023/api/chart \ + -H "Content-Type: application/json" \ + -d '{ + "data": "月份, 方案A, 方案B\n1月, 85, 78\n2月, 88, 82\n3月, 92, 88\n4月, 90, 95\n5月, 95, 98\n6月, 98, 102", + "chartType": "bar", + "title": "方案对比", + "theme": "gradient", + "enableSplit": true, + "splitIndex": 3, + "leftLabel": "上半年", + "rightLabel": "下半年", + "splitStyle": "dashed" + }' -o compare.png +``` + +**堆叠柱状图：** +```bash +curl -X POST http://192.168.0.101:16023/api/chart \ + -H "Content-Type: application/json" \ + -d '{ + "data": "季度, 线上, 线下, 批发\nQ1, 300, 200, 150\nQ2, 450, 280, 200\nQ3, 520, 350, 180\nQ4, 680, 400, 250", + "chartType": "bar", + "title": "渠道销售分布", + "stackMode": true, + "theme": "macarons" + }' -o stack.png +``` + +**高分辨率大图：** +```bash +curl -X POST http://192.168.0.101:16023/api/chart \ + -H "Content-Type: application/json" \ + -d '{ + "data": "产品, 2023, 2024, 2025\nA, 100, 200, 300\nB, 150, 250, 350", + "width": 1600, + "height": 900, + "pixelRatio": 3 + }' -o hd-chart.png +``` + +--- + +## 2. GET /api/chart + +通过 URL 参数生成图表，适合简单场景或直接在浏览器中使用。 + +### 参数 + +| 参数 | 说明 | +|------|------| +| `data` | CSV 数据（换行用 `\n` 表示，需 URL 编码） | +| `type` | 图表类型（bar / line / bar-line） | +| `title` | 图表标题 | +| `theme` | 主题风格 | +| `width` | 图片宽度 | +| `height` | 图片高度 | + +### curl 示例 + +```bash +curl "http://192.168.0.101:16023/api/chart?data=%E4%BA%A7%E5%93%81,Q1,Q2%0A%E6%89%8B%E6%9C%BA,100,200%0A%E5%B9%B3%E6%9D%BF,150,250&type=bar&title=%E6%B5%8B%E8%AF%95" -o chart.png +``` + +--- + +## 3. GET /api/health + +健康检查。 + +```bash +curl http://192.168.0.101:16023/api/health +``` + +返回： +```json +{ + "status": "ok", + "service": "data-chart-tool", + "version": "1.1.0", + "endpoints": { + "POST /api/chart": "生成图表图片（JSON body）", + "GET /api/chart": "生成图表图片（URL 参数）", + "GET /api/health": "健康检查" + } +} +``` + +--- + +## 数据格式说明 + +CSV 格式，规则： + +1. **第一行**：表头（系列名称） +2. **第一列**：横坐标值 +3. **其余单元格**：数值 +4. **分隔符**：逗号（自动识别制表符和 `|`） + +``` +类别, 系列1, 系列2, 系列3 +A, 10, 20, 30 +B, 15, 25, 35 +C, 20, 30, 40 +``` + +在 JSON 中用 `\n` 表示换行： +```json +{ + "data": "类别, 系列1, 系列2, 系列3\nA, 10, 20, 30\nB, 15, 25, 35\nC, 20, 30, 40" +} +``` + +--- + +## 各语言调用示例 + +### Python + +```python +import requests + +resp = requests.post('http://192.168.0.101:16023/api/chart', json={ + "data": "月份, 营收, 利润\n1月, 500, 80\n2月, 680, 120\n3月, 820, 160", + "chartType": "line", + "title": "增长趋势", + "theme": "dark", + "showLabel": True, + "width": 900, + "height": 500 +}) + +with open('chart.png', 'wb') as f: + f.write(resp.content) + +print(f"图片大小: {len(resp.content)} bytes") +``` + +### JavaScript (Node.js) + +```javascript +const fetch = require('node-fetch'); +const fs = require('fs'); + +const resp = await fetch('http://192.168.0.101:16023/api/chart', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + data: "产品, Q1, Q2\n手机, 1200, 2500\n平板, 800, 1300", + chartType: "bar", + title: "销售对比", + width: 800, + height: 500 + }) +}); + +const buffer = await resp.buffer(); +fs.writeFileSync('chart.png', buffer); +``` + +### JavaScript (浏览器 fetch) + +```javascript +const resp = await fetch('http://192.168.0.101:16023/api/chart', { + method: 'POST', + headers: { 'Content-Type': 'application/json' }, + body: JSON.stringify({ + data: "产品, Q1, Q2\n手机, 1200, 2500\n平板, 800, 1300", + chartType: "bar", + title: "销售对比" + }) +}); + +const blob = await resp.blob(); +const url = URL.createObjectURL(blob); +const img = document.createElement('img'); +img.src = url; +document.body.appendChild(img); +``` + +### Shell (保存到文件) + +```bash +curl -X POST http://192.168.0.101:16023/api/chart \ + -H "Content-Type: application/json" \ + -d '{"data":"A,B\n1,2\n3,4","chartType":"bar"}' \ + -o chart.png +``` + +--- + +## 主题预览 + +| 主题 | 说明 | 适用场景 | +|------|------|----------| +| `default` | 经典蓝绿配色 | 通用 | +| `dark` | 深色背景 + 高亮色 | 大屏展示、PPT | +| `macarons` | 柔和马卡龙色 | 清新风格 | +| `gradient` | 渐变色 + 圆角柱 | 现代感设计 | +| `retro` | 复古低饱和度 | 文艺风格 | + +--- + +## 错误处理 + +请求失败时返回 JSON： + +```json +{ + "error": "缺少 data 参数（CSV 格式数据）" +} +``` + +常见错误： + +| HTTP 状态码 | 原因 | +|:-----------:|------| +| 400 | 缺少 `data` 参数或数据格式错误 | +| 500 | 服务端渲染异常 | + +--- + +*文档更新时间：2026-07-16*