PyPI 官网下载 | restful-dj-2.0.0b1.tar.gz

# restful-dj 基于 Django2/3 的 restful 自动路由框架。 此包解决的问题： - 告别 Django 繁锁的路由配置 - 更便捷的 restful 编码体验 - 自动解析/校验请求参数，填充到路由处理函数 ## 安装 - Gitee: https://gitee.com/hyjiacan/restful-dj - Github: https://github.com/hyjiacan/restful-dj - PyPI: https://pypi.org/project/restful-dj/ ```shell script pip install restful-dj ``` ## 使用 此组件提供的包（package）名称为 `restful_dj`，所有用到的模块都在此包下引入。 示例： ```python from restful_dj import route from enums import RouteTypes @route('module_name', 'route_name', route_type = RouteTypes.TEST) def test(req): pass ``` 装饰器 [@route](#装饰器) 用于标记路由处理函数。`RouteTypes` 是自定义的路由数据。 `restful-dj` 包含以下几个部分： - 路由映射 > 为了避免在客户端暴露代码路径，从设计上使用了映射的方式来处理请求。 - [中间件](#注册中间件) > 在处理请求/响应过程中，可以对 `request`/`response` 以及其参数进行处理。 - [全局类型](#注册全局类型) > 在路由装饰器的参数中包含的全局类型，如 `RouteTypes` - [路由收集与持久化](#发布) > 为了提高线上性能的工具。 `restful-dj` 的使用流程如下： 1. [注册请求路径前缀](#注册请求路径前缀) 2. [注册路由映射](#注册路由映射) 3. [注册中间件](#注册中间件) 4. [编写路由处理函数](#编写路由处理函数) 5. [发布](#发布) ### 注册请求路径前缀 在项目的根 *urls.py* 文件中，使用以下配置 ```python from django.urls import path import restful_dj urlpatterns = [ path('any/prefix', restful_dj.dispatch) ] ``` 其中，`any/prefix` 是用户自定义的url前缀，可以使用空串 `''`，表示没有特定前缀。 `restful_dj.dispatch` 中路由的分发入口。 注：可以通过部署地址 `any/prefix` 访问接口列表 (仅在开发模式时可用)， 如：http://localhost:8000/any/prefix 。 ### 注册路由映射 为了避免在客户端暴露代码路径(同时避免意外访问未授权的代码)，从设计上使用了映射的方式来处理请求。 注册方式如下： ```python import restful_dj restful_dj.map_routes({ 'path.prefix': 'path.to', }) ``` - `path.prefix` 为请求的路径 - `path.to` 为请求路径时，应将其定向到的 python 包/模块。 所有的路由目录(顶层，不包含已经映射过目录的子目录)均需要被映射，未在映射表中的路径请求，不会被处理。 `restful-dj` 会自动查找 包/模块 `path.to` 下的所有路由。 > 路径应为基于项目根目录的相对路径。 ### 注册中间件 中间件用于在处理请求/响应过程中，对 `request`/`response` 以及其参数进行处理。 注册方式如下： ```python import restful_dj from path.to import FooMiddleware from path.to import BarMiddleware restful_dj.register_middlewares( FooMiddleware, BarMiddleware, ) ``` 当注册了多个中间件时，它们会按被注册的顺序执行。 **需要注意**： 每一个中间件类型在程序运行期间共享一个实例。 如何开发中间件？参见 [中间件类结构](#中间件类结构) ### 编写路由处理函数 路由文件位置没有要求，只要配置好就可以了。 ```python import restful_dj restful_dj.map_routes({ 'test': 'test.api' }) ``` 此配置表示，所有请求中以 `test` 开头的地址，都会交由 `test.api` 下的模块进行处理。 使用装饰器 [route](#装饰器) 标记路由处理函数。 *test/api/demo.py* ```python from django.http import HttpRequest from restful_dj.decorator import route @route(module='module-name', name='name') def get(request, param1, param2=None, param3: int =5): # request 会是 HttpRequest return { 'param1': param1, 'param2': param2, 'param3': param3, } @route(module='module-name', name='name') def get_param(param1, req: HttpRequest, from_=None, param3 =5): # req 会是 HttpRequest return { 'param1': param1, 'from': from_, 'param3': param3, } @route(module='module-name', name='name') def get_param(request: str, param1, from_=None, param3 =5): # request 会是请求参数，参数列表中没有 HttpRequest return { 'request': request, 'param1': param1, 'from': from_, 'param3': param3, } @route(module='module-name', name='name') def get_param(request, param1, from_=None, param3 =5, **kwargs): # 未在函数的参数列表中声明的请求参数，会出现在 kwargs 中 return { 'param1': param1, 'from': from_, 'param3': param3, 'variable_args': kwargs } ``` 一些需要注意的地方： - 当代码中需要使用关键字作为名称时，请在名称后添加 `_`，此时前端请求时，`_` 符号可省略， 如: `from_` 在请求时可写作 `from=test` （`from_=test` 亦可）。 - 对于语言间的命令差异，可以自动兼容 `下划线命名法` 与 `驼峰命名法`，如：请求参数中的 `pageIndex`，在处理函数中可以写作 `page_index`或`_page_index_` ， 也就是说，在前后添加 `_` 符号都不会影响参数的解析。 - 路由处理函数可以添加一个可变参数(如：`**kwargs**`)，用于接收未在参数列表中列出的请求项。 当然，`kwargs`和普通函数一样，可以是任何其它名称。 - `request` 参数(与参数位置无关)，可能被解析成三种结果(`1`和`2`均会将其作为 `HttpRequest` 参数处理)： 1. 参数名称为 `request`，并且未指定参数类型(或指定类型为 `HttpRequest`) 2. 参数类型为 `HttpRequest`，参数名称可以是任何合法的标识符 3. 参数名称为 `request`，声明了不是 `HttpRequest` 的类型，此时会被解析成一般的请求参数 前端调用: ```javascript // 请求 get 函数 ajax.get('test.demo?param1=1&param2=2&param3=3') // 请求 get_param 函数 ajax.get('test.demo/param?param1=1&param2=2&param3=3') ``` 路由可以返回任何类型的数据。路由会自动根据函数定义来判断传入参数的类型是否合法。 比如前面示例中的 `param3: int =5`，会根据声明类型 `int` 去判断传入类型 - 如果传入了字符串类型的数值，路由会自动转换成数值类型 - 另外，如果设置了 `None` 以外的默认值，那么路由会根据默认值的类型自动去判断， 此时可以省略参数类型，如: `param3: int =5` 省略为 `param3=5` ### 装饰器 装饰器 `route` 用于声明某个函数可以被路由使用。通过添加此装饰器以限制非路由函数被非法访问。 声明为： ```python def route(module=None, name=None, permission=True, ajax=True, referer=None, **kwargs): pass ``` - `module` 此路由所属的业务/功能模块名称 - `name` 此路由的名称 - `permission` 设置此路由是否有权限控制 - `ajax` 设置此路由是否仅允许 **ajax** 访问 *保留参数* - `referer` 设置此路由允许的 **referer** 地址 *保留参数* - `**kwargs` *额外参数* > 这些参数都会被传递给中间件的各个函数的参数 `meta`。详细见 [RouteMeta](#RouteMeta) 同时，此装饰器会自动尝试将 `request.body` 处理成 JSON 格式(仅在 `content-type=application/json` 时)，并且添加到 `request.B` 属性上。 另外，此装饰器会自动将 `request.GET` 和 `request.POST` 处理成为可以通过点号直接访问的对象，分别添加到 `request.G` 和 `request.P` 上。例： ```python # 原始数�