Flask RESTful API开发 资源与资源列表

REST API设计的核心是资源(Resource)，围绕着资源才有了URI和各种各样的HTTP操作。
因此，如何对资源建模就显得十分重要，
这关系到API能否为使用者提供他们想要的功能，
以及API的设计是否简明，便于维护。

资源和资源列表的URI

资源可以是独立的，比如每个单独的用户user。
也可以是一个集合，比如所有的用户users。

在用复数表示资源集合时，
可以对整个资源列表进行操作：
GET /users
也可以通过集合下单独个体的ID来获取具体某个资源：
GET /users/{userId}。

资源和资源列表的互相嵌套

这种“单个资源”与“资源列表”还可以继续互相嵌套下去，
比如每个用户可能有不止一个账号：
/users/{userId}/accounts/{accountId}

资源和资源列表的建模

在数据建模时，
可以将资源列表对应整个存储该类型资源的表格，
将单个资源对应表格中的每一行。
以Flask-SQLAlchemy为例，
定义UserModel对应所有用户的集合，映射整个存储用户的表格：

# models/user.py
class UserModel(db.Model):
    __tablename__ = 'users'

    @classmethod
    def find_by_name(cls, id):
        return cls.query.filter_by(id=id).first()

资源和资源列表的定义

如上文所示，
整个资源集合被一同建模，对应底层数据库的一个表格。
但如果我们想通过URI对单个资源和资源列表分别进行操作，
GET /users
GET /users/{userId}
最好在使用Flask-SQLAlchemy库进行资源定义时，
对单个资源和资源列表进行分别定义：

# resources/user.py
from flask_restful import Resource
from models.user import UserModel

class User(Resource):
  def get(self, id):
    user = UserModel.find_by_id(id)
      if user:
        return user.json(), 200
     return {'message': 'User not found'}, 404

class UserList(Resource):
  def get(self):
    return {'users': list(map(lambda x: x.json(), UserModel.query.all()))}

用户在使用API时，
既可以对user资源进行操作，
通过提供不同的userId查找对应的用户，
也可以对userList资源（即user的资源列表）进行操作，
返回所有的用户。

但不管是user还是userList，
都只与同一个模型：userModel进行交互。
对应到底层数据库也是一样，
都只对table users进行操作，
区别只是返回整个表格，
还是返回特定的某一行。

对资源和资源列表操作的分配

既然对同一种资源，
现在有了“单个资源”与“资源列表”两个并行的资源类，
对资源的各种操作就需要合理地分配到这两个类中。

比如对单个资源的获取，更新和删除，
适合放在“单个资源”的资源类下。

对资源集合的整体获取，和添加新的资源，
适合放在“资源列表”的资源类下。