前几天有人辗转找到公众号，留言询问之前一篇介绍 Flask-RESTPlus 文章的源代码（Flask Api 文档管理与 Swagger 上手），Flask-RESTPlus 虽然看起来非常方便，但在实际编写代码时总有种和当前项目结构冲突的感觉，因此整理之前的一篇改造某项目的总结，分享并探讨最佳实践。

在生成 Swagger 文档上，Flask-RESTPlus 是比较常用的 flask 拓展，但引入该插件需要对项目结构些许调整，如果是从 0 到 1 的新项目，倒也无伤大雅，但是对于已经存在的旧项目，改造还是有一定的工作量的，本文通过总结具体的项目改造，对 Flask-RESTPlus 进一步的讲解，以此总结。

蓝图与 API

在大型 Flask 项目中，为了防止各个模块的依赖混乱，一般通过模块划分，并在 app 工厂方法中统一对各个模块的蓝图进行注册，Flask-RESTPlus 作为 flask 拓展可以通过与 flask app 绑定从而托管注册在 Flask-RESTPlus 的视图，比如官方文档的例子：

app = Flask(__name__)
api = Api(app)

但是这样会架空 flask 自带的蓝图，如果是新项目的话可以考虑使用 Flask-RESTPlus 的 Namespace 替代，但是如果是老项目迁移，成本还是蛮高的，因此可以将 蓝图与 Flask-RESTPlus Api 绑定，这样既保留了原有的模块划分，还可以利用 Namespace 进行更细致的逻辑划分。

比如对于当然项目来说，其中有多个 blueprint，来分割相对独立的模块，我们拿 Resource 模块举例，通过 flask 的蓝图对大模块进行划分之后，再通过 Namespace 对细节再次划分：

desc = """
resource type 1, type 2, type 3, type 4, type 5 api
"""

resource_blueprint = Blueprint("Resource", __name__)
api = Api(resource_blueprint, version='1.0', title='Resource info',
          description=desc)
api.add_namespace(resource_type_1_api)
api.add_namespace(resource_type_2_api)
api.add_namespace(resource_type_3_api)
api.add_namespace(resource_type_4_api)
api.add_namespace(resource_type_5_api)

Resource 支持五种不同的类型，虽然这几种类型的 api 同属在一个蓝图里，但是其本身相对独立，因此可以使用 Namespace 做更细致的区分，然后将这五个 namespace 注册到 api 里。因此 blueprints 目录结构如下：

.
├── __init__.py
├── action
│   ├── __init__.py
│   ├── apis.py
│   └── dto.py
├── health.py
├── json_schema.py
└── resource
    ├── __init__.py
    ├── type_1.py
    ├── type_2.py
    ├── type_3.py
    ├── type_4.py
    ├── type_5.py
    └── dto.py
    

参数检查与权限验证

解决了注册问题，还有部分公共设施需要修改，比如参数检查和 api 权限认证。在之前是这样处理的：

@resource_blueprint.route("/", methods=['POST'])
@internal_token_validator
@request_json_validator(SEND_TYPE_1_SCHEMA)
@tracing_span("post_type_1:type_1_api")
def op_type_1():
    pass

token 验证的逻辑写在 internal_token_validator 装饰器中，虽然 Flask-RESTPlus api 类支持注册装饰器，但是因为并不是所有的 api 都需要 token 认证，因此并不能直接注册在其中，但是有认证的 api 比例非常多，依然选择装饰器，那么装饰数量将要突破 6 个而且到处写一样的逻辑非常丑，因此我继承了 Flask-RESTPlus 视图类 Resource，并复写了 dispatch 函数，如果有方法需要 token 认证则动态将 internal_token_validator 装饰器放在 method_decorators 中，而后者会在 Flask-RESTPlus 处理视图方法时调用。

虽然 Flask-RESTPlus 提供了提供了参数验证的功能，但是对我们来讲并不够用（并不强大），而 DCS 中的参数验证一直使用的是 json-schema，在上面的例子中 request_json_validator 装饰器便是处理相关逻辑，该装饰器会将一个 json-schema 规则传入，然后在处理该 api 函数前将 request 中的 json body 验证，如果验证失败便会封装一个友好的 400 Response。

为了方便使用 json-schema 验证，我也将相关逻辑封装了继承的视图基类里，相关代码：

class BaseView(Resource):
    json_schemas = {}
    internal_token_required = ['get', 'post', 'delete', 'put', 'patch']

    def dispatch_request(self, *args, **kwargs):
        from message.common.errors import APIError
        try:
            method = request.method.lower()
            self.validate(self.json_schemas.get(method))
            if method in self.internal_token_required:
                self.method_decorators.append(internal_token_validator)
            return super(BaseView, self).dispatch_request(*args, **kwargs)
        except APIError as e:
            rsp = Response(
                response=json.dumps(e.render()), status=e.status_code,
                mimetype='application/json')
            return rsp

    @staticmethod
    def validate(schema):
        from message.common.errors import APIError
        if not schema:
            return
        data = request.json
        try:
            validate(data, schema)
        except ValidationError as e:
            raise APIError("ARGS_ERROR", e.message, 400)

DTO

最后谈一下导包的问题，在前一篇文章也提到 Flask-RESTPlus 容易产生相互引用， 而工程和 demo 不同，不能通过什么魔法技巧来避免这个问题 ，而应该通过更加细致的模块划分来避免，最后看到文章《How to structure a Flask-RESTPlus web service for production builds》（文后附链接）中介绍了 DTO 才让我找到了更 “结构化” 的解决办法。

DTO 即 data transfer object，这样设计的思路是和蓝图类似，传统 flask 应用中，在 app 工厂方法注册蓝图，而蓝图内的包相对独立，而 Flask-RESTPlus 引入了 namespace，按上文，我们把它作为蓝图更细以级的存在，因此，可以参考蓝图，将 namespace 的定义和依赖封装在一个类中，这样既避免了循环引用，还可以让整个项目的结构更清晰。

比如 Type1 DTO：

class Type1Dto:
    api = Namespace("type1", path="/type1", decorators=[internal_token_validator])
    action_model = api.model('ActionModel', action_desc)
    create_model = api.model("CreateType1Model", {
        "type1_title": fields.List(fields.String(description="Type1 title"), required=True),
        "type1_info": fields.Nested(api.model("Type1InfoModel", {
            "content": fields.String(description="Type1 content"),
        }), required=True),
    })
    template_model = api.model("TemplateType1Model", {
        "type1_title": fields.List(fields.String(description="Type1 title", required=True)),
        "content": fields.Nested(api.model("TemplateContent", {}), required=True),
    })
    model = api.model("Type1Model", {
        "total": fields.Integer(readOnly=True, description="action total"),
        "results": fields.List(fields.Nested(action_model)),
    })

其中包含了 namespace 的定义，request 的格式对象（Flask-RESTPlus 基于它生成 Request 文档），和 response 的返回对象（Flask-RESTPlus 基于它渲染 json 并生成 Response 文档）。

在使用时，将 dto 导入到视图层，而相关 model 也会在这派上用场：

from .dto import Type1Dto

api = Type1Dto.api


@api.route("/")
class Type1Api(Resource):
    json_schemas = {"post": SEND_TYPE_1_SCHEMA}

    @tracing_span("post_type_1:type_1_api")
    @api.expect(Type1Dto.create_model)
    @api.param("Token", description="internal token.", _in="header", required=True)
    def post(self):
        actions = deal_with_type_1(api.payload['type_1_title'], api.payload['content'])
        result = {
            "total": len(actions),
            "results": [a.render() for a in actions]
        }
        return result

最后将视图层的 api 导入到蓝图定义的地方完成注册，这样整个项目既做到了合理的结构分类，也完成和解决了导包问题。

参考资料：《How to structure a Flask-RESTPlus web service for production builds》: https://medium.freecodecamp.org/structuring-a-flask-restplus-web-service-for-production-builds-c2ec676de563

Linux 通过 slab 分配器 分配 task_struct 结构。在 2.6 之前，各个进程的 task_struct 存放在他们内核栈的尾端，这样可以使得 x86 等寄存器比较少的硬件体系结构只要通过栈指针就能计算出它的位置，而对于现在比较新的硬件体系上，会专门拿出一个寄存器指向 task_struct，而只在进程内核栈的尾端保留一个 thread_info（定义在 asm/thread_info.h），其记录了执行线程的基础信息，并在 task 域中保留一个指向 task_struct 的指针。

PID

内核通过一个唯一的进程标识值（process identification value，PID）来表示每个进程，PID 是一个宏定义类型 pid_t，实际上就是一个 short int（为了保证兼容，采用 short 类型，最大值仅为 32768），对于 PID 最大有多大其实是受 linux/threads.h 中定义的限制，可以通过修改 /proc/sys/kernel/pid_max 来把 PID 增加至高达 400 万。但考虑到进程描述是存储在一个双向循环链表中的，进程越少意味着转一圈越快，进程数量巨大并不意味是一件好事。

进程的状态

在 task_struct 中，state 专门用来描述进程的当前状态，系统中的每个进程必然处于下面五种状态之一：

• TASK_RUNNING（运行）
• TASK_INTERRUPTIBLE（可中断）
• TASK_UNINTERRUPTIBLE（不可中断）
• __TASK_TRACED（被其他进程跟踪）
• __TASK_STOPPED（停止）

TASK_RUNNING 状态下意味着进程是可以被执行的，或许进程正在执行，也可能在运行队列中等待被执行（后面的进程调度会讲到），只有该状态下，进程才有被执行的可能。

TASK_INTERRUPTIBLE 状态意味着进程正在休眠，也许因为被阻塞，或者等待某些条件的达成，一旦这些条件达成，内核就会把进程状态设置为运行，处于此状态的进程也会因为接收到信号被唤醒并随时准备投入运行。

TASK_UNINTERRUPTIBLE 和 TASK_INTERRUPTIBLE 类似，但是不同点在于即使进程收到信号也不会被唤醒或者准备投入运行。该状态下的进程可以处于一个不受打扰的状态，以等待完成某些条件，比如进程创建初期，在没有初始化完成时便是处于该状态。

__TASK_TRACED 意味着被其他进程跟踪，比如通过调试程序进程跟踪等。

__TASK_STOPPED 意味着进程已经停止了执行，比如在收到 SIGSTOP，SIGTSTP，SIGTTIN，SIGTTOU 等信号，此外，在调试期收到任何信号都会进入该状态。更多进程的停止时发生的事情后面会讲到。

上下文与家族树

一般程序在用户空间执行，但当一个程序执行了系统调用或者触发了某个异常，它就会陷入内核空间，此时被称作内核 “代表进程执行” 并处于进程上下文中，一般情况下，在内核退出时，程序恢复到用户空间继续执行，系统调用和异常处理程序是对内核明确定义的接口，进程只有通过这些接口才能陷入内核执行，即对内核的所有访问都必须通过这些接口。在后面会单独拿一篇文章介绍系统调用。

Unix 系统的进程之间存在一个明显的继承关系，在 Linux 系统中也是如此，所有的进程都是 PID 为 1 的 init 进程的后代。而 init 进程是在系统启动的最后阶段启动的第一个进程。该进程负责读取系统的初始化脚本并执行其他的相关程序，以完成系统启动的最后过程。

除了 init 进程，系统的每个进程必有一个父进程，而每个进程也可以拥有零个到多个子进程，进程间呈现的树状关系，使得拥有相同父进程的两个子进程被称为 “兄弟”。进程的关系存放在进程描述符中，每个 task_struct 都包含一个指向其父进程 task_struct 的指针（被称为 parent 指针）。还包含一个称为 children 的子进程链表。也正是拥有这样的数据结构，可以从任意进程的 task_struct 遍历系统中存在的整个家族树。

进程的创建

Unix 系统的进程创建很特别，其他系统都提供了 Spawn 进程机制，首先在新的地址空间里创建进程，读入可执行文件，最好开始执行。这是一种符合直觉的进程创建方式，但是 Unix 采用了与众不同的方式，它把上述过程分成了两步（分成两个独立的函数），fork 和 exec。

首先 fork() 通过拷贝当前进程创建一个子进程，而子进程与父进程的区别仅在于 PID（进程 ID）、PPID（父进程的 PID）、部分资源和统计量（被挂起的信号等没必要继承的资源）。除此之外，新创建的子进程将直接使用父进程的资源（直接将相关指针指向父进程的资源）。而 exec() 函数负责读取可执行文件并将其载入地址空间开始运行。将这两个函数连起来使用可以达到其他系统单独使用 spawn 函数的作用。

Linux 的 fork() 使用写时拷贝（copy-on-wirte）页实现，这就意味着在创建子进程时可以推迟甚至免除拷贝父进程的数据。在 fork 时内核并不复制整个进程地址空间，而是让父进程和子进程共享同一个拷贝，只有到了需要写入的时候，数据才会被复制，从而使得各个进程拥有各自的拷贝。换句话说，资源的复制只会在需要写入的时候进行，在此之前，都是以只读的方式共享。因此 fork 的实际开销只有复制父进程的页表以及给子进程创建唯一的进程描述符。而且 Linux 做了一个巧妙的优化，在进程创建后会马上运行一个可执行文件，即先执行子进程，这样就避免了父进程对内存空间的修改导致触发写时拷贝。

Linux 通过 clone() 系统调用来实现 fork，而 fork() vfork() __clone() 函数都通过不同的参数来调用 clone() 系统调用，而 clone() 通过 do_frok()（定义在 kernel/fork.c）来完成 fork 绝大部分工作。

do_frok() 首选调用 copy_process 函数来拷贝进程，然后让进程开始运行，而 copy_process 函数即是 Linux 复制进程的具体实现：

1. copy_process 首先调用 dup_task_struck() 为子进程创建内核栈、thread_info 结构和 task_struct，目前这些结构和内容与父进程完全一致。
2. 检查并确保创建子进程后，用户所拥有的进程数目没有超过分配的资源限额。
3. 着手使子进程与父进程区别开来，进程描述符内的不能继承的成员被清零或者初始化。
4. 将进程状态设置为 TASK_UNINTERRUPTIBLE 避免被投入运行。
5. 调用 copy_flags() 更新 task_struct 的标记变量，比如标明进程是否拥有超级用户权限的 PF_SUPERPRIV 被清零，标明进程没有调用 exec() 函数的 PF_FORKNOEXEC 被设置。
6. 调用 alloc_pid() 获得一个有效的 PID
7. 根据 clone() 系统调用获得的参数来复制或者共享打开的文件、文件系统信息、信号处理函数、进程地址空间和命名空间等。
8. 最后 copy_process 做些收尾工作并返回一个指向子进程的指针。

这时运行权又回到了 do_frok() 上，do_frok() 会检查 copy_process 返回的指针，并让子进程投入运行，正如上面所说，会优先让子进程投入运行，然后是父进程。至此，一个子进程的创建便完成了。

线程

线程机制是现代编程技术中常用的一种抽象概念，该机制提供了在同一程序内共享内存地址空间运行的同一组线程。这些线程还可以共享如打开的文件等其他资源，但是如上文提到的，从 Linux 内核的角度来看，并没有线程这个概念，这和 Linux 线程的实现有关。

Linux 没为线程准备特别的调度算法或定义特别的数据结构，而是被视为一个与其他进程共享某些资源的进程。每个线程都拥有唯一隶属于自己的 task_struct，从内核的角度看，它就是一个普通的进程（只是线程和其他的一些进程共享某些资源而已）。

因此，Linux 的线程实现和 Windows 等其他操作系统的实现差距非常大，后者都在内核提供了专门的支持线程的机制（这些系统常把线程称为轻量级进程 lightweight processes）。”轻量级进程“ 这个说法本身就表现了 Linux 与其他系统的差异。其他系统中，相较于重量级进程，线程被抽象成一种耗费较少资源，运行迅速的执行单元，而在 Linux 中，进程本身就足够轻量，而线程只是进程间共享资源的手段而已。

因此，线程的创建也是通过 clone() 系统调用来实现，只不过在调用 clone() 时传递一些参数来标记需要共享的资源。

除了用户空间的线程外，内核经常需要在后台执行一些操作，这些任务一般是通过内核线程（kernel thread）完成。内核线程是独立运行在内核空间的标准进程，内核线程与普通进程的区别在于内核线程没有独立的地址空间（指向地址空间的 mm 指针为 NULL），它们只在内核空间运行，从不切换到用户空间去，而且内核进程和普通进程一样，可以被调度，可以被抢占。

在 Linux 可以通过 ps -ef 查看内核线程，内核线程只能通过内核线程创建，内核是通过从 kthreadd 内核进程中衍生出所有新的内核线程，其接口声明在 linux/kthread.h 中。内核线程启动后就一直运行直到调用 do_exit() 退出，或者由内核其他部分调用 kthread_stop() 退出，线程或者进程的终结，将在下面介绍。

进程的终结

当一个进程（线程）终结时，内核必须释放它所占有的资源并告知其父进程，而这两步便完成了资源释放和删除进程描述符。

释放资源

一般来说，进程的结束是由自身引起的，比如执行 exit()。但无论是主动或者被动，进程结束时都要靠 do_exit() 函数（定义在 kernel/exit.c）来 “处理身后事”：

1. 将 task_struct 中的标记成员设置为 PF_EXITING
2. 调用 del_timer_sync() 删除内核定时器，以确保没有定时器在排队，也没有定时器处理程序在运行。
3. 如果 BSD 的进程记账程序功能是开启的，则输出记账信息。
4. 调用 exit_mm() 来释放进程占用的 mm_struct，如果没有别的进程共享它，便彻底释放。
5. 调用 sem_exit()，如果进程排队等候 IPC 信号，则使它离开队列。
6. 调用 exit_file() 和 exit_fs()，以分别递减文件描述符、文件系统数据的引用计数，如果引用计数减低到零，则彻底释放。
7. 把存放在 task_struct 的 exit_code 成员设置为 exit() 函数提供的退出码。
8. 调用 exit_notify() 向父进程发送信号，并给退出进程的子进程寻找养父（养父为线程组中的其他任意进程或者 init 进程），并把退出进程的进程状态设置为 EXIT_ZOMBIE，即僵死状态。
9. 调用 schedule() 释放执行权，因为此进程已经设置为僵死状态，所以该进程再也不会被执行， do_exit() 永不会返回。

至此，进程的所有资源就已经全部被释放了，但是为了方便父进程查询退出进程的状态（退出码等），进程的 task_struct 会被保留，直到父进程执行 wait() 函数。

删除进程描述符

wait() 这一族函数都是通过唯一的系统调用 wait4() 实现的，它实现了挂起自己的进程，直到其中一个子进程退出，此时函数会返回该子进程的 PID。此外，调用该函数时提供的指针会包含子函数退出时的退出码。

当最终需要释放进程描述符时，release_task() 会被调用并执行下面的任务：

1. 调用 __exit_signal()，该函数调用 _unhash_process()，而后者又调用 detach_pid()，从 pidhash 上删除该进程，同时也会从任务列表中删除该进程。
2. _exit_signal() 释放目前僵死进程所使用的所有剩余资源，并进行最终统计和记录。
3. 如果这个进程是线程组的最后一个进程，并且领头进程已经死掉，那么继续通知僵死的领头进程的父进程。
4. 调用 put_task_struct() 释放进程内核栈和 thread_info 结构所占的页，并释放 task_struct 所占的 slab 高速缓存。

至此，进程描述符和进程独享资源就全部释放掉了。

孤儿进程

如果父进程在子进程退出前退出，必须有机制保证子进程能找到一个新的父亲，否则这些成为孤儿的进程会在退出时永远处于僵死状态。系统会遍历进程所在线程组的其他进程寻找养父，如果线程组没有其他进程，他就会被挂在 init 进程上。

一旦系统为进程成功找到并设置了新的父进程，就不会再有出现驻留僵死进程的风险了，而 init 进程也会例行调用 wait() 来检查其子进程，清除所有与其相关的僵死进程。

总结

进程是一个非常基础和关键的抽象概念，位于每种现代操作系统的核心位置，本文通过介绍进程及其生命周期来描述其基本概念，下一篇会通过介绍进程的调度来描述进程运行时的样子。

有一份文档详细的介绍了所有的魔术方法的使用方式，本文只整理了常用魔术方法以及常见的坑。 文档见： http://pycoders-weekly-chinese.readthedocs.io/en/latest/issue6/a-guide-to-pythons-magic-methods.html

构造与析构

Python 对象通过 __init__ 进行初始化，但是在执行 __init__ 之前，首先被执行的是 __new__ 函数。在初始化一个对象时，会先调用 __new__ 方法，该方法是一个类方法，执行完相关逻辑之后调用 __init__ 并将初始化参数传递给后者。

而 __del__ 函数是 Python 对象的析构函数，无论是垃圾回收还是手动删除，都是执行这个方法：

class Model(object):
    def __init__(self):
        print("Run: __init__")

    def __del__(self):
        print("Run: __del__")


if __name__ == "__main__":
    m = Model()
    del m

结果：

Run: __init__
Run: __del__

打印

在 Python 魔术方法中，有两个和打印有关，__repr__ 和 __str__。

如果在 Python 直接打印一个类，将会获得一个内存地址：

<__main__.Model object at 0x10408fda0>

如果在解释器中想获得一个更友好的显示，__repr__ 是一个非常好的选择。另外，在不把 object 当做字符串处理的场合，也是会使用该方法。

而在把 object 当做字符串处理或者转换为字符串的场合，比如 print(object)、"{}".format(object)、str(object) 等，__str__ 将会被使用。

class Model(object):
    def __init__(self):
        self.id = uuid.uuid4()
        self.content = "fluent python demo"

    def __str__(self):
        return self.content

    def __repr__(self):
        return "<Model: {}>".format(self.id)

一般在 __str__ 中展现更人性化的信息，可能直接返回给用户；而 __repr__ 更多为了在调试中使用方便（解释器中等）。

另外，如果 __str__ 没有定义，那么将会直接使用 __repr__ 方法，因此如果不需要太多差别，只定义后者即可。

数组与字典

如果需要定义一个类似列表的自定义类，为了支持通过下标访问，可以覆写 __getitem__。

class Model(object):
    def __init__(self):
        self.content = [r for r in range(0, 3)]

    def __getitem__(self, item):
        return self.content[item]

该类从此支持了下标访问，并且还支持切片，排序等 Python 内置方法：

if __name__ == "__main__":
    m = Model()
    print(m[1:], sorted(m, reverse=True))

结果：

[1, 2] [2, 1, 0]

对于赋值操作，只需要覆写 __setitem__ 方法：

def __setitem__(self, key, value):
    self.content[key] = value

同理，对于将自定义对象进行类似字典的操作，可以这样实现：

class Model(object):
    def __init__(self):
        self.content = {
            "key": "value"
        }

    def __getitem__(self, item):
        return self.content[item]

    def __setitem__(self, key, value):
        self.content[key] = value

类成员变量

类成员方法 __getattr__、__getattribute__、__setattr__ 是三个方便且危险的方法，可以用来定义类成员属性，前两个是用来获取，最后一个是用来赋值。

前两个的区别是 __getattribute__ 会被首先调用，只有 __getattribute__ 找不到的时候,才会调用 __getattr__。

因为本身的类属性操作也是基于这几个方法，因此在覆写时应该避免循环调用最后栈溢出。

总结

简单讲了几种常见的魔术方法，魔术方法可以使得自定义类型支持 Python 原生、内置方法，因而使得代码风格更加简洁和一致。但是，也容易写出难以调试的魔法代码，简洁（或者说 geek）和可维护性可能本身就是两个极端，在使用魔术方法时还需要考虑后继维护者是否能理解自己的行为。