Ajenti 插件开发指南：通过 HttpPlugin 与 @endpoint 构建 HTTP 处理接口-平芜编程栈

后端
运维

【免费下载链接】ajenti

Ajenti Core and stock plugins

项目地址：https://gitcode.com/gh_mirrors/aj/ajenti

导读

本文围绕 docs/source/dev/http.rst 的开发者文档展开，系统讲解 Ajenti 插件如何注册并处理 HTTP 请求：从继承HttpPlugin抽象接口、使用@get/@post等路由装饰器，到用@endpoint开启 JSON API 模式或底层页面模式，再到HttpContext提供的完整响应控制能力。读完本文，你将能够为 Ajenti 编写出可被前端直接调用的 REST 风格 API 端点，并理解请求从 WSGI 进入后经 master/worker 架构最终派发到插件处理器的完整链路。

一、Ajenti 的 HTTP 请求处理架构概览

Ajenti 采用 master/worker 的多进程架构：主进程（master）负责会话管理与请求接收，每个登录会话由独立的 worker 子进程承载（参见 aj/gate/gate.py 中WorkerGate对 gipc 管道与子进程的封装）。一次 HTTP 请求的生命周期大致如下：

WSGI 请求进入HttpRoot，被包装为HttpContext（aj/http.py）；
GateMiddleware依据 Cookie 会话或 HTTP Basic 认证找到（或新建）对应 worker，将序列化后的HttpContext通过管道发送过去（aj/gate/middleware.py）；
worker 进程内的Worker.handle_http_request反序列化上下文，交给AuthenticationMiddleware与CentralDispatcher组成的中件栈（aj/gate/worker.py）；
CentralDispatcher遍历所有已注册的HttpPlugin实例，命中路由则执行对应处理函数并返回结果（aj/routing.py）。

因此，插件的 HTTP 能力本质上就是向HttpPlugin这一接口注册组件。理解这条链路有助于定位"为什么我的端点没被调用"之类的问题：路由匹配、方法匹配与认证检查都发生在 worker 进程内。

二、定义 HTTP 端点：HttpPlugin 接口与路由装饰器

2.1 继承 HttpPlugin

插件通过扩展aj.api.http.HttpPlugin抽象类来提供自己的 HTTP 端点，并用jadi的@component机制注册，例如：

from jadi import component from aj.api.http import get, HttpPlugin @component(HttpPlugin) class Handler(HttpPlugin): def __init__(self, context): self.context = context @get(r'/api/demo4/calculate/(?P<operation>\w+)/(?P<a>\d+)/(?P<b>\d+)') def handle_api_calculate(self, http_context, operation=None, a=None, b=None): http_context.respond_ok() return 'Hello!'

HttpPlugin在 aj/api/http.py 中定义：其handle(http_context)方法会遍历类字典中带有url_pattern属性的方法，用编译后的正则匹配http_context.path，命中后将命名捕获组作为关键字参数传入处理函数。__init__(self, context)中保存的context携带身份信息（context.identity）、worker 引用等运行时数据。

2.2 请求方法装饰器：@get、@post、@delete、@head、@put、@patch

aj.api.http通过requests_decorator_generator动态生成了完整的 HTTP 方法装饰器（aj/api/http.py）：

标准 HTTP 方法：get、post、delete、head、put、patch；
WebDAV 方法：propfind、mkcol、options、proppatch、copy、move、lock、unlock（Ajenti 的文件管理、WebDAV 相关功能即依赖这些方法）。

用法统一为：

@get(r'/api/foo/(?P<id>\d+)') def handle_foo(self, http_context, id=None): ...

装饰器接收一个 URL 正则pattern，^与$是隐式添加的，即整个路径必须完全匹配（参见 aj/api/http.py 中re.compile(f'^{pattern}$')）。正则中的命名捕获组（(?P<name>...)）会在匹配后作为**kwargs注入处理函数。

方法匹配由HttpPlugin.handle内部的check_method完成（aj/api/http.py），规则如下：

处理函数标注的 method 与http_context.method（取自REQUEST_METHOD，统一转为大写）一致才可调用；
HEAD 请求被允许打在 GET 目标上，以兼容健康检查等场景；
处理函数返回值若为str会被编码为 UTF-8 字节；若为生成器（types.GeneratorType，如流式文件下载）则原样透传（aj/api/http.py）。

2.3 旧式 @url 装饰器的兼容

代码库中还存在较早的url(pattern)装饰器（aj/api/http.py），它只绑定url_pattern而不绑定 method。HttpPlugin.handle在检测到方法上没有method属性时会回退到旧式兼容路径，并输出日志警告Backward @url compatibility ...。新代码应一律使用@get/@post等按方法区分的装饰器。

三、@endpoint：API 模式与页面模式

原文档强调："建议给所有 HTTP 处理方法都加上@endpoint装饰器"。endpoint(page=False, api=False, auth=True)定义在 aj/api/endpoint.py，三个参数含义如下：

参数	默认值	作用
`auth`	`True`	要求已认证会话，否则返回`401 Unauthenticated`
`api`	`False`	将响应与异常自动包装为 JSON，并特殊处理`EndpointError`
`page`	`False`	启用页面模式，提供对 HTTP 响应的底层控制

3.1 @endpoint(api=True)：自动 JSON 编码

import time from jadi import component from aj.api.http import get, HttpPlugin from aj.api.endpoint import endpoint, EndpointError, EndpointReturn @component(HttpPlugin) class Handler(HttpPlugin): def __init__(self, context): self.context = context @get(r'/api/demo4/calculate/(?P<operation>\w+)/(?P<a>\d+)/(?P<b>\d+)') @endpoint(api=True) def handle_api_calculate(self, http_context, operation=None, a=None, b=None): start_time = time.time() try: if operation == 'add': result = int(a) + int(b) elif operation == 'divide': result = int(a) / int(b) else: raise EndpointReturn(404) except ZeroDivisionError: raise EndpointError('Division by zero') return { 'value': result, 'time': time.time() - start_time }

这是原文档给出的完整示例。在api=True模式下（aj/api/endpoint.py）：

处理函数的返回值（dict、list 等）会经simplejson.dumps序列化为 JSON；
自动写入Content-Type: application/json响应头；
异常按类型转换为对应 HTTP 状态码与 JSON 错误体（详见下文第四节）。

3.2 @endpoint(page=True)：底层响应控制

当你需要完全控制响应头、返回非 JSON 内容（如 HTML、XML、文件流）时，使用page=True：

@get(r'/api/test') @endpoint(page=True) def handle_api_calculate(self, http_context): http_context.add_header('Content-Type', '...') content = "Hello!" # return http_context.respond_not_found() # return http_context.respond_forbidden() # return http_context.file('/some/path') http_context.respond_ok() return content

在页面模式下，@endpoint不会自动序列化返回值，也不会把异常转成 JSON：EndpointError、SecurityError与其他异常都会直接向上抛出（aj/api/endpoint.py），由CentralDispatcher捕获并渲染错误页。处理函数负责自己调用http_context的响应方法（见第五节）。

注意@endpoint是包裹在路由装饰器外层的：装饰顺序为上例所示，即先@get标记路由，再@endpoint包装执行逻辑，二者缺一不可。

四、异常与状态码的约定：EndpointError、EndpointReturn、SecurityError

@endpoint的异常处理逻辑定义了 Ajenti API 的错误语义（aj/api/endpoint.py）：

EndpointReturn(code)：主动返回指定 HTTP 状态码，可在响应体中附带data。例如上述计算 API 中对未知操作raise EndpointReturn(404)。它的语义是"可预见的业务性返回"，不会触发客户端崩溃对话框；
EndpointError(message)：表示"可预见的错误"（如除零、参数非法）。在api=True模式下转为500状态码，并返回包含message、exception类名与traceback的 JSON 对象（aj/api/endpoint.py）；
SecurityError：权限不足时抛出，api=True模式下转为403 Forbidden（aj/api/endpoint.py）。SecurityError定义于 aj/auth.py，其 message 形如Forbidden: permission "..." is required；
未捕获的普通异常：在api=True模式下同样转为500并返回带 traceback 的 JSON，便于前端排查；在page=True模式下则重新抛出交给上层。

另外，若处理函数内部已通过http_context.respond('404 Not Found')等方式设置过状态，@endpoint会检测context.status中不含200的情况并加以传播（aj/api/endpoint.py）。

五、HttpContext：请求数据与响应控制

每个处理函数接收的第一个参数都是HttpContext实例（aj/http.py）。它的主要属性包括：

属性	说明
`env`	WSGI 环境字典
`path`	URL 路径段
`method`	请求方法（大写）
`headers`	响应头列表（键值对元组）
`body`	请求体（字节串）
`query`	合并后的查询参数与表单参数
`response_ready`	是否已提交过响应

5.1 读取请求数据

查询字符串与表单：HttpContext.__init__会同时解析 URL 查询串（cgi.FieldStorage）与application/x-www-form-urlencoded、multipart/form-data表单体（CGIFieldStorage），合并到query字典中（aj/http.py）；
JSON 请求体：http_context.json_body()直接对self.body做 UTF-8 解码与json.loads（aj/http.py）。plugins/check_certificates/views.py 中的真实插件就是通过http_context.json_body()['url']读取 POST 载荷的。

5.2 响应方法速查

原文档提示"参见aj.http.HttpContext获取可用的http_context方法"，以下是从 aj/http.py 提取的完整响应工具集：

方法	效果
`respond(status)`	以任意状态行创建响应（`response_ready = True`）
`respond_ok()`	`200 OK`
`respond_server_error()`	`500 Server Error`，返回`[b'Server Error']`
`respond_unauthenticated()`	`401 Unauthenticated`
`respond_forbidden()`	`403 Forbidden`
`respond_not_found()`	`404 Not Found`
`respond_bad_request()`	`400 Bad Request`
`redirect(location)`	`302 Found`并写入`Location`头
`add_header(key, value)`	追加响应头
`remove_header(key)`	移除指定响应头
`gzip(content, compression=6)`	返回 gzip 压缩响应，自动设置`Content-Encoding`与`Content-Length`
`file(path, stream=False, inline=False, name=None)`	返回文件内容响应（见 5.3）
`run_response()`	最终调用 WSGI`start_response()`，补齐`X-Frame-Options: SAMEORIGIN`与 CSP 安全头

5.3 file()：内置的静态文件服务

HttpContext.file()是页面模式下最实用的方法之一，它已经处理了完整 HTTP 语义（aj/http.py）：

路径穿越防护：路径含..直接返回 403；
MIME 类型映射：.html、.css、.js、.png、.jpg、.svg、.woff、.pdf均有对应Content-Type，其余回落为application/octet-stream；
条件请求：支持If-Modified-Since返回304 Not Modified，支持Range返回206 Partial Content；
下载语义：inline=True时为内联展示，否则为attachment下载，并支持自定义filename；
流式读取：stream=True时以 100 KB 缓冲块配合gevent.sleep(0)让步逐块产出，适合大文件。

六、从源码看真实插件的 HTTP 端点写法

6.1 证书检查插件（@post + JSON 请求体）

plugins/check_certificates/views.py 展示了 POST 端点的标准范式：

@component(HttpPlugin) class Handler(HttpPlugin): def __init__(self, context): self.context = context @post(r'/api/check_cert') @endpoint(api=True) def handle_api_check_cert(self, http_context): url = http_context.json_body()['url'] return json.loads(json.dumps(checkOnDom(*url.split(':'))))

6.2 Augeas 插件（URL 参数 + EndpointReturn）

plugins/augeas/views.py 演示了命名捕获组与业务性 404 的组合：

@get(r'/api/augeas/endpoint/(?P<id>.+)') @endpoint(api=True) def handle_api_get(self, http_context, id=None): ep = self.__get_augeas_endpoint(id) if not ep: raise EndpointReturn(404) aug = ep.get_augeas() ...

此外，plugins/core/views/api.py 中集中体现了完整的方法矩阵：@get('/api/core/identity')、@post('/api/core/auth')、@delete('/api/core/totps/(?P<timestamp>\d*)')等，可作为编写 CRUD 风格端点的参考范本。

七、请求处理流程与路由解析的源码级印证

理解以下细节有助于调试端点不生效的问题：

Worker 内建处理器栈：Worker.__init__构建了HttpMiddlewareAggregator([AuthenticationMiddleware, CentralDispatcher])（aj/gate/worker.py），并在每个请求到来时再叠加所有HttpMiddleware组件（aj/gate/worker.py）；
认证检查：AuthenticationMiddleware.handle会处理 SSL 客户端证书并写入X-Auth-Identity头（aj/auth.py）；@endpoint(auth=True)（默认）在context.identity为空时直接返回 401；
中央派发：CentralDispatcher.handle遍历HttpPlugin.all(self.context)的所有实例，依次调用instance.handle(http_context)，谁返回非None输出就用谁的结果；全部未命中则落入InvalidRouteHandler渲染 404 页面（aj/routing.py）。路由的^...$全匹配语义也意味着：若你的正则写成了不带锚点的前缀匹配，路径就不会命中；
worker 超时：master 等待 worker 响应的默认超时为 600 秒，超时返回504 Gateway Timeout（aj/gate/middleware.py），因此长时间运行的任务不应阻塞在 HTTP 处理函数内。

结语

Ajenti 的 HTTP 处理模型非常简洁：HttpPlugin负责把"类方法"映射为"URL 路由"，@endpoint负责把"普通函数"升级为"带认证、带 JSON 编码、带错误约定的标准端点"，HttpContext则提供了构建任意响应（文件、压缩流、重定向、自定义状态码）的全部底层能力。掌握这三层抽象，再对照 plugins/core/views/api.py 等仓库内真实插件的写法，即可为 Ajenti 快速添加稳定的 API 端点。