框架规范和支持的参数
API words
URL
| url字段名称 | 简要说明 | 例子 |
|---|---|---|
| < collection> | 资源名称，支持3种名称：模型名、别名、表名 | "/Users", "/users", "/user" |
| < key> | id or key_field | "/users/1", "/users/@windprozhao" |
| < attribute> | 子资源 |
api supports
| method | scope | description |
|---|---|---|
| GET | collection | 获取一个资源列表 |
| GET | resource | 获取单个资源 |
| POST | resource | 新增资源 |
| PUT,PATCH | resource | 更新资源 |
| DELETE | resource | 删除资源 |
params
查询参数
| 参数 | 格式 | 支持并列条件 | description | 例子 |
|---|---|---|---|---|
| _page | int | 否 | 数据分页页数 | /users?_page=1&_num=20 |
| _num | int | 否 | 数据分页每页数量 | /users?_page=1&_num=20 |
| _expand | int | 否 | 资源展开的层级 | /users?_expand=1 |
| _orders | "字段:排序类型" asc or desc | 是 | 数据排序 | 单个字段排序：/users?_orders=id:asc 多个字段排序：/users?_orders[]=id:asc&_orders[]=code:desc |
| _fields | "表名:字段1,字段2" | 是 | 字段白名单限制 | 限制单一种类资源：/users?_fields=users:id,name,groups 限制多种资源：/users?_fields[]=users:id,name,groups&_fields[]=groups:id |
| _except | "表名:字段1,字段2" | 是 | 字段黑名单限制 | 限制单一种类资源：/users?_except=users:id,name,groups 限制多种资源：/users?_except[]=users:id,name,groups&_except[]=groups:id |
| _match | string | 否 | 以"或"为条件搜索模型配置：match_fields | /users?_match="zhao" |
字段过滤
| 格式 | 支持并列条件 | description | 例子 |
|---|---|---|---|
| {attr}={value} | 是 | 过滤指定字段 | 过滤单一值：/users?name=windprozhao 列表查询：/users?name[]=windpro1&name[]=windpro2 |
| {attr}=%{value}% | 否 | 模糊查询指定字段 | 过滤单一值：/users?name=windpro% 语法与mysql like 类似。 |
| {sub_resource}.{attr}={value} | 是 | 过滤子资源字段 | 组为 admin 的用户：/users?groups.name=admin 列表查询：/users?groups.name[]=admin&groups.name[]=normal |
| {sub_resource}.match={value} | 是 | 搜索子资源配置：match_fields | 组为 ad* 的用户：/users?groups._match=ad |
HTTP status code
注:[400,503]为错误的范围
| 返回码 | 简要说明 |
|---|---|
| 200 | 请求正确；更新成功(PUT) |
| 201 | 创建成功 |
| 204 | 删除成功 |
| 206 | 成功，但有warnning |
| 400 | 失败。字段错误, 头字段不支持, 非法路径 |
| 401 | 失败。表示用户没有权限（令牌、用户名、密码错误）。 |
| 403 | 失败。表示用户得到授权（与401错误相对），但是访问是被禁止的。 |
| 404 | 失败。资源未找到 |
| 406 | 失败。用户请求的格式不可得（比如用户请求JSON格式，但是只有XML格式）。 |
| 500 | 错误。内部错误、超时 |
| 503 | 错误。服务器繁忙 |
error type
| 类型 | 简要说明 |
|---|---|
| Unknown | 未知错误。自定义错误。 |
| PermissionDenied | 权限错误 |
| AccessDenied | 非法访问。一般出现在路径不存在等 |
| RequestHeadersAcceptNotSupport | Headers:ACCEPT 类型不支持 |
| RequestHeadersContentTypeNotSupport | Headers:Content-type 类型不支持 |
| RestAssertionError | 断言异常 |
| ResourceNotFound | 资源不存在 |
| ResourceRelationNotExists | 资源关系不存在 |
| IllegalRequestData | 提交数据错误。一般出现在数据校验 |
| StatementErrorException,DatabaseExecutionError,DatabaseConnectionError | 数据库错误 |
| ResourcesAlreadyExists | 资源已存在，无法创建 |
| ForeignKeyConstraintFails | 外键依赖异常 |
| ResourcesConstraintNotNullable | 字段必须非空 |
| ResourcesConstraintNotDefaultValue | 字段没有默认值 |