API 概览

矩海无人船系统提供了完整的 API 接口，支持 REST、WebSocket 和 Python SDK。

API 版本

当前版本: v1

Base URL: http://localhost:8080/api/v1

认证

所有 API 请求需要进行身份认证。

JWT 认证

# 获取 Token
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "password"}'

# 响应
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400
}

# 使用 Token
curl -X GET http://localhost:8080/api/v1/devices \
  -H "Authorization: Bearer <token>"

API Key 认证

curl -X GET http://localhost:8080/api/v1/devices \
  -H "X-API-Key: your-api-key"

API 类别

1. 设备管理 API

管理 USV 设备连接和状态。

• GET /devices - 获取设备列表
• GET /devices/{id} - 获取设备详情
• POST /devices - 添加设备
• PUT /devices/{id} - 更新设备配置
• DELETE /devices/{id} - 删除设备

2. 控制 API

控制 USV 运动和行为。

• POST /control/move - 控制移动
• POST /control/stop - 停止运动
• POST /control/return - 返回起点
• GET /control/status - 获取控制状态

3. 任务 API

创建和管理任务。

• GET /missions - 获取任务列表
• GET /missions/{id} - 获取任务详情
• POST /missions - 创建任务
• PUT /missions/{id} - 更新任务
• DELETE /missions/{id} - 删除任务
• POST /missions/{id}/start - 开始任务
• POST /missions/{id}/pause - 暂停任务
• POST /missions/{id}/stop - 停止任务

4. 数据 API

查询和导出数据。

• GET /data/telemetry - 获取遥测数据
• GET /data/sensors - 获取传感器数据
• POST /data/export - 导出数据
• GET /data/stream - WebSocket 实时数据流

5. 系统 API

系统配置和监控。

• GET /system/info - 系统信息
• GET /system/health - 健康检查
• GET /system/logs - 系统日志
• PUT /system/config - 更新配置

通用响应格式

成功响应

{
  "success": true,
  "data": {
    ...
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

错误响应

{
  "success": false,
  "error": {
    "code": "DEVICE_NOT_FOUND",
    "message": "Device with ID 'USV-001' not found",
    "details": {}
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

错误码

错误码	HTTP状态码	说明
UNAUTHORIZED	401	未授权
FORBIDDEN	403	禁止访问
NOT_FOUND	404	资源不存在
VALIDATION_ERROR	400	参数验证失败
DEVICE_NOT_CONNECTED	503	设备未连接
MISSION_IN_PROGRESS	409	任务正在进行
INTERNAL_ERROR	500	内部错误

速率限制

默认速率限制：

• 认证用户: 100 请求/分钟
• 未认证: 20 请求/分钟

响应头：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705315800

分页

支持分页的端点使用以下参数：

GET /api/v1/missions?page=1&per_page=20&sort=created_at&order=desc

响应包含分页信息：

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 100,
    "pages": 5
  }
}

WebSocket API

连接

const ws = new WebSocket('ws://localhost:8081?token=<jwt_token>');

ws.onopen = () => {
  console.log('Connected');
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

消息格式

{
  "type": "telemetry",
  "device_id": "USV-2024-001",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "latitude": 31.2304,
    "longitude": 121.4737,
    "speed": 5.2,
    "heading": 90,
    "battery": 78
  }
}

Python SDK

安装

pip install jhusv-sdk

快速开始

from jhusv import Client

# 创建客户端
client = Client(
    host='localhost',
    port=8080,
    api_key='your-api-key'
)

# 获取设备列表
devices = client.devices.list()

# 获取设备状态
status = client.devices.get('USV-2024-001')

# 创建任务
mission = client.missions.create({
    'name': 'water_survey',
    'type': 'waypoint',
    'waypoints': [...]
})

# 启动任务
client.missions.start(mission.id)

API 使用示例

示例 1: 获取实时位置

curl -X GET \
  'http://localhost:8080/api/v1/data/telemetry?device=USV-2024-001&limit=1' \
  -H 'Authorization: Bearer <token>'

示例 2: 控制 USV 移动

curl -X POST \
  'http://localhost:8080/api/v1/control/move' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "device_id": "USV-2024-001",
    "latitude": 31.2354,
    "longitude": 121.4787,
    "speed": 5
  }'

示例 3: 创建并启动任务

# 创建任务
curl -X POST \
  'http://localhost:8080/api/v1/missions' \
  -H 'Authorization: Bearer <token>' \
  -H 'Content-Type: application/json' \
  -d @mission.json

# 启动任务
curl -X POST \
  'http://localhost:8080/api/v1/missions/{id}/start' \
  -H 'Authorization: Bearer <token>'

更多信息

• 📝 Control API - 详细的控制接口
• 📊 Data API - 数据查询和导出
• 🔌 WebSocket API - 实时数据流

支持

• 📖 查看完整 API 文档
• 💬 加入开发者社区
• 🐛 报告问题