feat: person api

[trim21]

获取人物列表

router: /api/v0/persons

分页参数 /api/v0/persons?limit=30&offset=60
排序参数 /api/v0/persons?sort=$sort&order=$order sort 可选项 id, name, update order可选项-1, 1

filter:
router: /api/v0/persons?name=和田薫
router: /api/v0/persons?career=$career，目前可选项为 producer, mangaka, artist, seiyu, writer, illustrator, actor，可重复出现。如?career=artist&career=seiyu，多个职业之间为或关系。

以上filter可以组合使用，相互之间为逻辑且

{
  "total": 2,
  "limit": 30, //default 30, max 50
  "offset": 0,
  "data": [
    {
      "id": 1,
      "name": "水樹奈々",
      "type": 1,
      "career": [
        "artist",
        "seiyu"
      ],
      "locked": false,
      "img": "a6/e8/1_prsn_ZdFfp.jpg?r=1597241889",
      "short_summary": "原名 近藤 奈々（こんどう なな），日本女性声优兼歌手。有个妹妹名字是近藤美香，为Daisy×Daisy主唱。\r\n\r\n简介\r\n自小受业余经营歌谣教室的父母影响，..."
    },
    {
      "id": 3,
      "name": "和田薫",
      "type": 1,
      "career": [
        "producer",
        "artist"
      ],
      "locked": false,
      "img": "ec/cb/3_prsn_anidb.jpg",
      "short_summary": "日本作曲家。于1962年5月5日出生于山口县下关市。17岁开始自己独自学习作曲技法与和声学。1981年，于山口县立豊浦高中毕业以后，进入东京音乐大学作曲系学习，..."
    }
  ]
}

获取单个人物详情

router: /api/v0/persons/{person_id}

200

{
  "id": 2,
  "name": "遠藤明範",
  "type": 1,
  "locked": false,
  "role": ["producer", "writer"],
  "summary": "日本の脚本家、作家。神奈...",
  "img": null,
  // 从wiki中解析，$.infobox 可能为null，$.infobox.* 不会为null
 "infobox": [
    {
      "key": "简体中文名",
      "value": "水树奈奈"
    },
    {
      "key": "别名",
      "value": [
        {
          "k": "日文名",
          "v": "近藤奈々 (こんどう なな)"
        },
        {
          "k": "纯假名",
          "v": "みずき なな"
        },
        {
          "k": "罗马字",
          "v": "Mizuki Nana"
        },
        {
          "k": "昵称",
          "v": "奈々ちゃん、奈々さん、奈々様、お奈々、ヘッド"
        }
      ]
    },
    {
      "key": "性别",
      "value": "女"
    },
    {
      "key": "生日",
      "value": "1980年1月21日"
    },
    {
      "key": "血型",
      "value": "O型"
    },
  ],
  // 下面的字段由旧服务器从infobox中解析，值可能为null
  "gender": "male",
  "blood_type": "O",
  "birth_year": null,
  "birth_mon": 19,
  "birth_day": 9,
  "stat": {
    "comments": 110,
    "collects": 841
  }
}

307:

如果人物被合并

相关条目

router: /api/v0/persons/{person_id}/subjects

[
    {
      "id": 4,
      "staff": "开发",
      "name": "メタルスラッグ7",
      "name_cn": "合金弹头7",
      "image": "https://lain.bgm.tv/pic/cover/c/a8/7f/4_cMMK5.jpg"
    },
    {
      "id": 5,
      "staff": "发行",
      "name": "Call of Duty 4",
      "name_cn": "使命召唤 4: 现代战争",
      "image": "https://lain.bgm.tv/pic/cover/c/e4/da/5_wUARf.jpg"
    },
    {
      "id": 6,
      "staff": "遊戲設計師",
      "name": "Team Fortress 2",
      "name_cn": "军团要塞2",
      "image": "https://lain.bgm.tv/pic/cover/c/16/79/6_gC3iJ.jpg"
    }
]

统一错误响应

404:

{
  "title": "Not Found",
  "description": "resource you resource can't be found in the database",
  "detail": {
    "person_id": "20"
  }
}

422:

person id不是正整数，比如/api/v0/person/0

{
  "title": "Invalid Request",
  "description": "One or more parameters to your request was invalid.",
  "detail": [
    {
      "loc": [
        "path",
        "person_id"
      ],
      "msg": "ensure this value is greater than 0",
      "type": "value_error.number.not_gt",
      "ctx": {
        "limit_value": 0
      }
    }
  ]
}

[codecov-commenter]

Codecov Report

Merging #3 (45ab03a) into master (36a9502) will increase coverage by 7.94%.
The diff coverage is 94.98%.

@@            Coverage Diff             @@
##           master       #3      +/-   ##
==========================================
+ Coverage   84.88%   92.83%   +7.94%     
==========================================
  Files          23       27       +4     
  Lines         450      795     +345     
==========================================
+ Hits          382      738     +356     
+ Misses         68       57      -11     

Impacted Files	Coverage Δ
pol/db_models/sa.py	100.00% <ø> (ø)
pol/db/const.py	78.26% <78.26%> (ø)
pol/utils/__init__.py	88.88% <80.00%> (+48.88%)	⬆️
pol/api/v0/person.py	88.33% <89.71%> (+36.33%)	⬆️
pol/api/v0/models.py	100.00% <100.00%> (ø)
pol/curd/__init__.py	100.00% <100.00%> (+35.71%)	⬆️
pol/db/_const.py	100.00% <100.00%> (ø)
pol/db/const_test.py	100.00% <100.00%> (ø)
pol/db/mysql.py	100.00% <100.00%> (ø)
pol/db/tables.py	100.00% <100.00%> (+1.04%)	⬆️
... and 14 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 36a9502...45ab03a. Read the comment docs.

[weizhenye]

type 不应该用中文吧；role 字段从扩展性上来说，个人偏好用数组；推荐遵循 RESTful 规范，路由中表示集合的部分一般用复数 /persons/{id} 这样。

我之前练习接口设计，纯粹看 Bangumi 页面功能梳理了数据模型关系，涉及到 wiki 的我都放弃了，太复杂了。其他部分可以看下，希望能提供一些参考。

接口：https://weizhenye.github.io/bangumi-restful-api/#/%E4%BA%BA%E7%89%A9
模型：https://weizhenye.github.io/bangumi-restful-api/#model-Person

[trim21]

type 不应该用中文吧

目前有很多预定义的变量都是直接硬编码的。这个之后导出一下，放到个新仓库或者json之类的。比如这个巨大的staff job map

现在的表是这样的，所以你设计的很多字段都没法做(bgm38)

https://github.com/bangumi/server/wiki/%E4%BA%BA%E7%89%A9#%E5%9F%BA%E7%A1%80%E4%BF%A1%E6%81%AF