Rest-o-matic

基于JSON的自动API生成器，包括SQL查询组合器和WSGI端点路由器

警告：此软件处于alpha版，API或函数签名在完全发布前可能会更改。

用法

此软件包包括三个主要组件

Rest-o-matic端点/ API描述

此系统会自动为使用包含的SQL查询组合器和WSGI端点路由器的表生成JSON端点

使用以下命令创建一组新的端点

from restomatic.json_sql_compositor import SQLiteDB
from restomatic.wsgi_endpoint_router import EndpointRouter
from restomatic.endpoint import register_restomatic_endpoint

table_mappers = {
    'table_name': ['column1', 'column2', ...],
    ...
}

db = SQLiteDB(database_filename, table_mappers)

router = EndpointRouter()

register_restomatic_endpoint(router, db, 'table_name', ['GET', 'PUT', 'POST', 'PATCH', 'DELETE'])
...

任何一组方法都是有效的。如果没有提供方法，并且disallow_other_methods设置为True，则将返回405方法不允许错误。

GET（如果找到则返回200，否则返回404）

GET one: /table/1

返回：作为JSON对象（字典）请求的行

POST（创建成功返回201，搜索成功返回200）

此端点创建一行（或多行新行），也支持类似get的搜索（但不受uri大小/格式的限制）

POST one: /table
    body: {...}
or POST many: /table
    body: [{...}, {...}]
or POST-based search: /table/search (returns 200 if found, 404 if no matches)
    body: {'where': [...search criteria...]}
    Optionally, can also include in addition to the where clause:
    'limit': 1, 'offset': 2, 'order_by': ['column_1', {'column': 'column_2', 'direction': 'ASC'}]

返回创建实例的ID。

PUT（成功返回200）

此端点可以创建或更新指定的行

PUT one: /table
    body: {...} (if ID specified, update, otherwise create)
or PUT many: /table
    body: [{...}, {...}] (if ID specified, update, otherwise create)

PATCH（成功返回200）

此端点根据给定的where条件更新指定的行

PATCH one: /table/1
    body: {...}
or PATCH many: /table/where
    body: {'where': [...search criteria...], 'set': {...}}

DELETE（成功返回200）

此端点根据给定的where条件删除指定的行

DELETE one: /table/1
or DELETE many: /table/where
    body: {'where': [...search criteria...]}

搜索条件格式

搜索条件是一个包含两个或三个元素的列表，即列、比较运算符和值（除非运算符不需要值。）此外，可以通过将所有所需的比较语句（两个或三个元素的列表）添加到具有“and”或“or”键的字典中，将搜索条件与“and”或“or”组合。（见以下示例）

搜索条件示例

['id', 'isnotnull']
['id', 'eq', 1]
['value', 'lt', 1.3]
['id', 'gte', 2]
['description', 'like', '%ABC%']
['value', 'isnull']
['description', 'in', ['test 1', 'test 5']]
['description', 'not_in', ['test 1', 'test 2', 'test 3']]

运算符应该是以下之一

'eq', '=', '=='
'lt', '<'
'gt', '>'
'lte', '<='
'gte', '>='
'in'
'notin', 'not_in'
'like'
'isnull', 'is_null'
'isnotnull', 'is_not_null'

（每行的运算符是等效的）

示例搜索

POST /test/search
{'where': ['id', 'lte', 3]}

使用AND语句

POST /test/search
{
    'where': {
        'and': [
            ['id', 'lte', 3],
            ['id', '>', 1]
        ]
    }
}

SQL查询组合器/ SQLite数据库接口

这提供了一种方便且安全的方式来与本地SQLite数据库交互，允许通过Python函数构建SQL查询，而不是通过字符串操作。它还支持参数绑定，以防止最常见的SQL注入攻击。

要使用查询组合器，首先创建一个数据库引用

db = SQLiteDB('test.db', table_mappers)

如果不存在，这将创建数据库文件（但不创建表）。您还可以提供 ':memory:' 以创建一个仅内存的sqlite数据库。

然后可以执行选择、更新、插入和删除语句，如下所示

db.select_all('test').where({'and': [['id', 'gte', 2], ['id', 'lt', 3]]}).one() == (2, 'test 2', 1.5)
db.select_all('test').where(['id', 'isnotnull']).all_mapped() == [{'id': 1, 'description': 'test 1', 'value': 0.5}]
db.select_all('test').count().scalar() == 2
db.select_all('test').where(['id', 'gte', 3]).one_or_none_mapped() is None
db.insert('test', ('description', 'value')).values(('test 2', 1.5))
db.insert_mapped('test', ({'description': 'test 3', 'value': 3.0}, {'description': 'test 4', 'value': 4.4}))
db.delete('test').where(('id', 'eq', 4)).run()
db.update_mapped('test', {'value': 2.0}).where(('id', 'eq', 1)).run()
db.commit() # Required for persisting any transactional changes.

请注意，通常映射形式的 _mapped() 会返回类似JSON的字典，普通形式会返回元组，无论是表顺序（对于 select_all）还是指定的列顺序。此外，scalar() 只返回第一个值，例如对于计数查询。此外，所有()函数返回结果列表，而 one() 只返回一个（如果未找到则引发错误），one_or_none() 返回一个结果或未找到时返回 None。

此外，请注意，过滤函数（如 where 和 order_by）使用的格式与上述API格式相同，并由restomatic端点使用。

请参阅测试文件，了解所有可能的用法和返回值/格式。

WSGI端点路由器

这提供了一种轻量级且方便的方式，根据请求方法（GET、PUT、POST、PATCH、DELETE）和请求的URI（如 /index 或 /table）来路由多个端点。它还支持URI的精确匹配和前缀匹配，并自动解析/返回纯文本、JSON和表单输入、HTML输出的格式。

可以通过以下方式实例化

from restomatic.wsgi_endpoint_router import EndpointRouter

router = EndpointRouter(default_in_format='plain', default_out_format='plain')

可选地指定服务器默认格式。

然后注册端点，如下所示

router.register_endpoint(endpt_index, exact='/', method='GET')
router.register_endpoint(endpt_get_json, prefix='/get_json', method='GET', out_format='json')
router.register_endpoint(endpt_patch_json, exact='/patch_json', method='PATCH', in_format='json', out_format='json')

每个端点定义首先指定处理端点调用的函数，并允许指定精确匹配或前缀匹配、要处理的HTTP方法以及自动处理的输入和输出格式。

端点函数具有此签名

def endpoint_index(request):
    ...create data...
    return data

返回值可以是以下之一

response_data
response_data, status_code
response_data, status_code, additional_headers

其中附加头可以采用以下格式

{'X-Example': 'Header-Value'}

或

[('Content-Type', 'text/plain')]

如果提供了内容类型头，则可以使用它根据端点定义覆盖默认值。

请参阅测试文件，了解所有可能的用法和返回值/格式。

高级用法（预/后处理等）

此外，您可以添加预处理器和后处理器，以执行数据输入的验证，并用于自定义类型处理。

这些可以在数据库连接时添加，例如

db = SQLiteDB('file.db', table_mappers, preprocessors={
    'table_name': {
        'description': description_validator,
        'value': value_preprocessor,
    },
}, postprocessors={
    'table_name': {
        'value': value_postprocessor,
    }
})

预处理器可以抛出异常来指示无效数据，这将终止当前的SQL查询或请求。

后处理器可以以其他方式格式化数据（不同于内部数据格式），并且与匹配的预处理器一起使用，可以有效地创建自定义数据类型。

预处理器和后处理器的函数签名应该是

def value_processor(value, **context):
    ... code here ...
    return value

请注意，函数名称和第一个变量名称（对于值）都不重要，可以命名为最适合您的代码的名称。上下文变量用于捕获有关此预处理器或后处理器正在从中运行的当前和未来上下文信息。目前，上下文仅针对预处理器设置，'db' 设置为正在运行的db实例，'mode' 变量设置为当前模式，即 'INSERT INTO'、'UPDATE' 或 'WHERE'（用于搜索/获取）。

请注意，两种处理器类型都应该返回新的处理值，以便将其插入数据库（预-）或返回给用户（后-），当然，对于验证器或条件处理器，这可以与输入值相同。

外键支持

默认情况下，sqlite不强制执行外键，要启用支持，只需在数据库连接时设置标志即可

db = SQLiteDB('example.db', table_mappers, enable_foreign_key_constraints=True)

如果外键约束不满足，则会抛出 sqlite3.IntegrityError。

安装

需要 Python 3.6+ 以及无其他外部依赖。然而，需要 WSGI 服务器，例如 uWSGI。

要使用 uWSGI，可以按以下方式安装

pip3 install uwsgi

可能需要依赖包（根据系统而定）如 python3-dev 和 build-essential 来安装 uWSGI，完整说明请参阅：https://uwsgi-docs.readthedocs.io/en/latest/WSGIquickstart.html

此外，要运行单元测试，需要 pytest，并推荐使用 pytest-cov。

计划功能

• 更强大的数据库支持，包括 PostgreSQL / MySQL
• 支持更多类型，如枚举和布尔类型
• 自动创建表，以及检查约束（如范围/正数等）
• 可以使用装饰器、授权和日志记录以实现更好的安全性和定制
• 支持 JOIN 操作和可能的外键关系加载
• 支持 Flask（可选使用提供的 WSGI 路由器替代）