📖
加载中...
📖
加载中...
开发者接入指南 — 5 分钟接入 Poetry Gateway
Poetry Gateway 是中国古诗词数据的统一 API 网关。所有客户端 (Flutter、Web、小程序)统一通过 Gateway 获取诗词数据,不直接访问 底层 Chinese Poetry API。
Base URL
https://your-domain.com/api/v1// poetry_repository.dart
import 'package:dio/dio.dart';
class PoetryRepository {
final Dio _dio = Dio(BaseOptions(
baseUrl: 'https://your-domain.com/api/v1',
connectTimeout: Duration(seconds: 10),
));
// 首页数据
Future<Map<String, dynamic>> getHome() async {
final res = await _dio.get('/home');
return res.data['data'];
}
// 诗词列表
Future<Map<String, dynamic>> getPoems({
int page = 1, String? dynasty, String? type,
}) async {
final res = await _dio.get('/poems', queryParameters: {
'page': page, 'dynasty': dynasty, 'type': type,
});
return res.data['data'];
}
// 搜索
Future<Map<String, dynamic>> search(String query) async {
final res = await _dio.get('/search', queryParameters: {'q': query});
return res.data['data'];
}
}const API = 'https://your-domain.com/api/v1';
// 首页数据
const home = await fetch(API + '/home').then(r => r.json());
// { success: true, data: { featuredPoem, featuredAuthor, ... } }
// 分页诗词
const poems = await fetch(
API + '/poems?page=1&pageSize=20&dynasty=唐'
).then(r => r.json());
// 随机诗词(飞花令)
const random = await fetch(
API + '/poems/random?char=春&author=李白'
).then(r => r.json());
// 搜索
const results = await fetch(
API + '/search?q=静夜思&type=title'
).then(r => r.json());Poetry Gateway 使用 JWT Bearer Token 进行认证。以下端点需要认证:
/ai/*/user/profile/favorites/*/history/*// 1. 注册或登录获取 Token
const login = await fetch(API + '/user/login', {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email: 'user@example.com', password: '123456' }),
}).then(r => r.json());
const token = login.data.token; // JWT Token
// 2. 后续请求携带 Token
const favs = await fetch(API + '/favorites', {
headers: { 'Authorization': `Bearer ${token}` },
}).then(r => r.json());
// 3. Token 有效期 7 天,过期后重新登录成功 (200)
{
"success": true,
"data": { ... }
}失败
{
"success": false,
"code": "NOT_FOUND",
"message": "资源不存在"
}| HTTP 状态码 | Code | 说明 |
|---|---|---|
| 400 | VALIDATION_ERROR | 参数校验失败 |
| 401 | UNAUTHORIZED | 未登录或 Token 过期 |
| 404 | NOT_FOUND | 资源不存在 |
| 429 | RATE_LIMITED | 请求过于频繁 |
| 500 | INTERNAL_ERROR | 服务器内部错误 |
| 502 | UPSTREAM_ERROR | 上游服务不可用 |