isanic-e 0.1.0__py3-none-any.whl

isanic/__init__.py

@@ -0,0 +1,19 @@
+"""iSanic-e 框架公共接口。"""
+
+from isanic.controller import ApiController
+from isanic.exceptions import AppError, ValidationAppError
+from isanic.handlers import setup_exception_handlers
+from isanic.response import ApiResponse, fail, success, wrap_response
+from isanic.routing import register_controllers
+
+__all__ = [
+    "ApiController",
+    "ApiResponse",
+    "AppError",
+    "ValidationAppError",
+    "fail",
+    "register_controllers",
+    "setup_exception_handlers",
+    "success",
+    "wrap_response",
+]

isanic/cli.py

@@ -0,0 +1,103 @@
+import argparse
+import re
+import shutil
+import sys
+from pathlib import Path
+
+TEMPLATE_ROOT = Path(__file__).parent / "templates" / "full"
+PROJECT_NAME_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*$")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """命令行入口。"""
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "init":
+        return init_project(args.project_name)
+
+    parser.print_help()
+    return 0
+
+
+def init_project(project_name: str, base_dir: Path | None = None) -> int:
+    """初始化完整示例项目。"""
+    if not PROJECT_NAME_PATTERN.fullmatch(project_name):
+        print(
+            "项目名只能包含字母、数字、短横线和下划线，并且必须以字母开头。",
+            file=sys.stderr,
+        )
+        return 2
+
+    root_dir = base_dir or Path.cwd()
+    target_dir = root_dir / project_name
+    if target_dir.exists() and any(target_dir.iterdir()):
+        print(f"目标目录已存在且非空：{target_dir}", file=sys.stderr)
+        return 1
+
+    target_dir.mkdir(parents=True, exist_ok=True)
+    _copy_template(TEMPLATE_ROOT, target_dir, project_name)
+    _print_success(project_name)
+    return 0
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    """构建命令行参数解析器。"""
+    parser = argparse.ArgumentParser(
+        prog="isanic",
+        description="iSanic-e 项目脚手架",
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    init_parser = subparsers.add_parser("init", help="初始化一个 Sanic 项目")
+    init_parser.add_argument("project_name", help="要创建的项目目录名")
+    return parser
+
+
+def _copy_template(source_dir: Path, target_dir: Path, project_name: str) -> None:
+    """递归复制模板文件到目标目录。"""
+    for source_path in source_dir.rglob("*"):
+        if _should_skip_template_path(source_path):
+            continue
+
+        relative_path = source_path.relative_to(source_dir)
+        target_path = target_dir / _render_text(str(relative_path), project_name)
+
+        if source_path.is_dir():
+            target_path.mkdir(parents=True, exist_ok=True)
+            continue
+
+        target_path.parent.mkdir(parents=True, exist_ok=True)
+        text = source_path.read_text(encoding="utf-8")
+        target_path.write_text(_render_text(text, project_name), encoding="utf-8")
+
+    gitignore_template = target_dir / "_gitignore"
+    if gitignore_template.exists():
+        shutil.move(str(gitignore_template), str(target_dir / ".gitignore"))
+
+
+def _should_skip_template_path(path: Path) -> bool:
+    """跳过安装后自动生成的缓存文件。"""
+    if "__pycache__" in path.parts:
+        return True
+    return path.suffix in {".pyc", ".pyo"}
+
+
+def _render_text(value: str, project_name: str) -> str:
+    """替换模板中的占位符。"""
+    return value.replace("{{ project_name }}", project_name)
+
+
+def _print_success(project_name: str) -> None:
+    """输出初始化成功提示。"""
+    print(f"项目已创建：{project_name}")
+    print("")
+    print("下一步：")
+    print(f"  cd {project_name}")
+    print('  python -m pip install -e ".[dev]"')
+    print("  python -m pytest")
+    print("  python -m app.main")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

isanic/controller.py

@@ -0,0 +1,13 @@
+from typing import ClassVar
+
+from sanic import Request
+
+
+class ApiController:
+    """控制器基类。"""
+
+    prefix: ClassVar[str | None] = None
+    request: Request
+
+    def __init__(self, request: Request) -> None:
+        self.request = request

isanic/exceptions.py

@@ -0,0 +1,31 @@
+from typing import Any
+
+
+class AppError(Exception):
+    """业务异常基类。"""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: int | str = "APP_ERROR",
+        status_code: int = 400,
+        data: Any = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.status_code = status_code
+        self.data = data
+        super().__init__(message)
+
+
+class ValidationAppError(AppError):
+    """请求参数校验失败。"""
+
+    def __init__(self, errors: list[dict[str, Any]]) -> None:
+        super().__init__(
+            "请求参数校验失败",
+            code="VALIDATION_ERROR",
+            status_code=422,
+            data=errors,
+        )

isanic/handlers.py

@@ -0,0 +1,39 @@
+from sanic import Sanic
+from sanic.exceptions import MethodNotAllowed, NotFound, SanicException
+
+from isanic.exceptions import AppError
+from isanic.response import fail
+
+
+def setup_exception_handlers(app: Sanic) -> None:
+    """注册全局异常处理器。"""
+
+    @app.exception(AppError)
+    async def handle_app_error(request, exception: AppError):
+        return fail(
+            exception.code,
+            exception.message,
+            exception.data,
+            status=exception.status_code,
+        )
+
+    @app.exception(NotFound)
+    async def handle_not_found(request, exception: NotFound):
+        return fail("NOT_FOUND", "接口不存在", status=404)
+
+    @app.exception(MethodNotAllowed)
+    async def handle_method_not_allowed(request, exception: MethodNotAllowed):
+        return fail("METHOD_NOT_ALLOWED", "请求方法不允许", status=405)
+
+    @app.exception(Exception)
+    async def handle_unknown_error(request, exception: Exception):
+        if isinstance(exception, SanicException):
+            status_code = exception.status_code or 500
+            return fail(
+                "HTTP_ERROR",
+                str(exception) or "请求处理失败",
+                status=status_code,
+            )
+
+        request.app.ctx.logger.exception("未捕获异常", exc_info=exception)
+        return fail("INTERNAL_SERVER_ERROR", "服务器内部错误", status=500)

isanic/response.py

@@ -0,0 +1,67 @@
+from dataclasses import asdict, is_dataclass
+from typing import Any, Generic, TypeAlias, TypeVar
+
+from pydantic import BaseModel
+from sanic.response import HTTPResponse, json
+
+T = TypeVar("T")
+
+JsonValue: TypeAlias = (
+    dict[str, Any] | list[Any] | str | int | float | bool | None
+)
+
+
+class ApiResponse(Generic[T]):
+    """统一响应结构的类型标记。"""
+
+    code: int | str
+    message: str
+    data: T | None
+
+
+def success(data: Any = None, message: str = "success", code: int = 0) -> HTTPResponse:
+    """返回成功响应。"""
+    return json(
+        {
+            "code": code,
+            "message": message,
+            "data": _to_jsonable(data),
+        }
+    )
+
+
+def fail(
+    code: int | str,
+    message: str,
+    data: Any = None,
+    status: int = 400,
+) -> HTTPResponse:
+    """返回失败响应。"""
+    return json(
+        {
+            "code": code,
+            "message": message,
+            "data": _to_jsonable(data),
+        },
+        status=status,
+    )
+
+
+def wrap_response(value: Any) -> HTTPResponse:
+    """把业务返回值包装为统一响应。"""
+    if isinstance(value, HTTPResponse):
+        return value
+    return success(value)
+
+
+def _to_jsonable(value: Any) -> Any:
+    """转换常见 Python 对象为可 JSON 序列化的数据。"""
+    if isinstance(value, BaseModel):
+        return value.model_dump(mode="json")
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, dict):
+        return {key: _to_jsonable(item) for key, item in value.items()}
+    if isinstance(value, list | tuple | set):
+        return [_to_jsonable(item) for item in value]
+    return value

isanic/routing.py

@@ -0,0 +1,141 @@
+import inspect
+import pkgutil
+import re
+from collections.abc import Awaitable, Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any, TypeAlias
+
+from sanic import Request, Sanic
+from sanic.response import HTTPResponse
+
+from isanic.controller import ApiController
+from isanic.response import wrap_response
+from isanic.validation import build_form_model, resolve_form_binding
+
+ControllerClass: TypeAlias = type[ApiController]
+HandlerResult: TypeAlias = HTTPResponse | dict[str, Any] | list[Any] | str | int | float | bool | None
+ControllerMethod: TypeAlias = Callable[..., Awaitable[HandlerResult]]
+
+HTTP_METHODS = {"get", "post", "put", "patch", "delete"}
+CONTROLLER_SUFFIX = "Controller"
+
+
+def register_controllers(app: Sanic, package: str) -> None:
+    """扫描指定包并注册所有控制器路由。"""
+    root_module = import_module(package)
+    for module in _walk_modules(root_module):
+        for controller_class in _iter_controller_classes(module):
+            _register_controller(app, controller_class)
+
+
+def _walk_modules(root_module: ModuleType) -> list[ModuleType]:
+    """递归加载包下所有模块。"""
+    modules = [root_module]
+    if not hasattr(root_module, "__path__"):
+        return modules
+
+    for module_info in pkgutil.walk_packages(
+        root_module.__path__,
+        prefix=f"{root_module.__name__}.",
+    ):
+        modules.append(import_module(module_info.name))
+    return modules
+
+
+def _iter_controller_classes(module: ModuleType) -> list[ControllerClass]:
+    """查找模块中定义的控制器类。"""
+    controllers: list[ControllerClass] = []
+    for _, item in inspect.getmembers(module, inspect.isclass):
+        if item is ApiController:
+            continue
+        if item.__module__ != module.__name__:
+            continue
+        if issubclass(item, ApiController):
+            controllers.append(item)
+    return controllers
+
+
+def _register_controller(app: Sanic, controller_class: ControllerClass) -> None:
+    """注册单个控制器上的所有 HTTP 方法。"""
+    controller_prefix = _controller_prefix(controller_class)
+    for route in _iter_routes(controller_class):
+        uri = f"/{controller_prefix}/{route.path}".rstrip("/")
+        app.add_route(
+            _build_route_handler(controller_class, route.method_name),
+            uri,
+            methods=[route.http_method],
+            name=f"{controller_class.__name__}.{route.method_name}",
+        )
+
+
+class RouteInfo:
+    """控制器方法对应的路由信息。"""
+
+    def __init__(self, http_method: str, method_name: str, path: str) -> None:
+        self.http_method = http_method
+        self.method_name = method_name
+        self.path = path
+
+
+def _iter_routes(controller_class: ControllerClass) -> list[RouteInfo]:
+    """解析控制器类中的路由方法。"""
+    routes: list[RouteInfo] = []
+    for name, member in inspect.getmembers(controller_class, inspect.isfunction):
+        http_method, path = _parse_route_method(name)
+        if http_method is None or path is None:
+            continue
+        routes.append(RouteInfo(http_method, name, path))
+    return routes
+
+
+def _parse_route_method(name: str) -> tuple[str | None, str | None]:
+    """把方法名解析为 HTTP 方法和路径。"""
+    parts = name.split("_", 1)
+    method = parts[0].lower()
+    if method not in HTTP_METHODS:
+        return None, None
+
+    action = parts[1] if len(parts) > 1 else "index"
+    return method.upper(), _to_kebab_case(action)
+
+
+def _build_route_handler(
+    controller_class: ControllerClass,
+    method_name: str,
+) -> Callable[[Request], Awaitable[HTTPResponse]]:
+    """创建 Sanic 可识别的路由处理函数。"""
+    controller_method = getattr(controller_class, method_name)
+    form_binding = resolve_form_binding(controller_method)
+
+    async def route_handler(request: Request) -> HTTPResponse:
+        controller = controller_class(request)
+        method = getattr(controller, method_name)
+        if form_binding is None:
+            result = await method()
+        else:
+            form = build_form_model(request, form_binding)
+            result = await method(form)
+        return wrap_response(result)
+
+    route_handler.__name__ = f"{controller_class.__name__}_{method_name}"
+    return route_handler
+
+
+def _controller_prefix(controller_class: ControllerClass) -> str:
+    """生成控制器路径前缀。"""
+    if controller_class.prefix:
+        return controller_class.prefix.strip("/")
+
+    name = controller_class.__name__
+    if name.endswith(CONTROLLER_SUFFIX):
+        name = name[: -len(CONTROLLER_SUFFIX)]
+    return _to_kebab_case(name)
+
+
+def _to_kebab_case(value: str) -> str:
+    """把类名或方法名片段转换为短横线命名。"""
+    value = value.replace("_", "-")
+    value = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "-", value)
+    value = re.sub(r"(?<=[A-Z])(?=[A-Z][a-z])", "-", value)
+    return value.lower()

isanic/templates/full/README.md

@@ -0,0 +1,32 @@
+# {{ project_name }}
+
+这是通过 `isanic init` 生成的 Sanic 后端项目。
+
+## 快速开始
+
+安装依赖：
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+运行测试：
+
+```bash
+python -m pytest
+```
+
+启动服务：
+
+```bash
+python -m app.main
+```
+
+示例接口：
+
+```text
+GET  /hello/test
+POST /login/submit
+GET  /users/list?page=1&size=10
+GET  /users/raw
+```

isanic/templates/full/_gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

isanic/templates/full/app/__init__.py

@@ -0,0 +1 @@
+"""应用包。"""

isanic/templates/full/app/api/__init__.py

@@ -0,0 +1 @@
+"""业务接口包。"""

isanic/templates/full/app/api/controllers/__init__.py

@@ -0,0 +1 @@
+"""控制器包。"""

isanic/templates/full/app/api/controllers/hello.py

@@ -0,0 +1,9 @@
+from isanic import ApiController
+
+
+class Hello(ApiController):
+    """示例控制器。"""
+
+    async def get_test(self) -> dict[str, str]:
+        """测试接口。"""
+        return {"message": "hello"}

isanic/templates/full/app/api/controllers/login.py

@@ -0,0 +1,28 @@
+from sanic.response import text
+
+from app.api.schemas.login import LoginForm, UserQueryForm
+from isanic import ApiController, AppError
+
+
+class Login(ApiController):
+    """登录控制器。"""
+
+    async def post_submit(self, form: LoginForm) -> dict[str, str]:
+        """提交登录表单。"""
+        if form.username == "disabled":
+            raise AppError("用户已被禁用", code="USER_DISABLED", status_code=403)
+        return {"token": f"token-for-{form.username}"}
+
+
+class UserProfile(ApiController):
+    """用户资料控制器。"""
+
+    prefix = "users"
+
+    async def get_list(self, form: UserQueryForm) -> dict[str, int]:
+        """查询用户列表。"""
+        return {"page": form.page, "size": form.size}
+
+    async def get_raw(self):
+        """直接返回 Sanic 原生响应。"""
+        return text("raw response")

isanic/templates/full/app/api/schemas/__init__.py

@@ -0,0 +1 @@
+"""请求和响应模型包。"""

isanic/templates/full/app/api/schemas/login.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel, Field
+
+
+class LoginForm(BaseModel):
+    """登录表单。"""
+
+    username: str = Field(min_length=3, max_length=32)
+    password: str = Field(min_length=6, max_length=128)
+
+
+class UserQueryForm(BaseModel):
+    """用户列表查询表单。"""
+
+    page: int = Field(default=1, ge=1)
+    size: int = Field(default=10, ge=1, le=100)

isanic/templates/full/app/common/__init__.py

@@ -0,0 +1 @@
+"""通用工具包。"""

isanic/templates/full/app/core/__init__.py

@@ -0,0 +1 @@
+"""核心配置和应用工厂包。"""

isanic/templates/full/app/core/app.py

@@ -0,0 +1,17 @@
+from sanic import Sanic
+
+from app.core.config import Settings, load_settings
+from app.core.logging import configure_logging
+from isanic import register_controllers, setup_exception_handlers
+
+
+def create_app(settings: Settings | None = None) -> Sanic:
+    """创建 Sanic 应用实例。"""
+    resolved_settings = settings or load_settings()
+    app = Sanic(resolved_settings.app_name)
+    app.ctx.settings = resolved_settings
+    app.ctx.logger = configure_logging(resolved_settings.debug)
+
+    setup_exception_handlers(app)
+    register_controllers(app, resolved_settings.controllers_package)
+    return app

isanic/templates/full/app/core/config.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+import os
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    """应用运行配置。"""
+
+    app_name: str = "{{ project_name }}"
+    host: str = "127.0.0.1"
+    port: int = 8000
+    debug: bool = False
+    auto_reload: bool = False
+    controllers_package: str = "app.api.controllers"
+
+
+def load_settings() -> Settings:
+    """从环境变量加载配置。"""
+    return Settings(
+        app_name=os.getenv("APP_NAME", "{{ project_name }}"),
+        host=os.getenv("APP_HOST", "127.0.0.1"),
+        port=int(os.getenv("APP_PORT", "8000")),
+        debug=_to_bool(os.getenv("APP_DEBUG"), default=False),
+        auto_reload=_to_bool(os.getenv("APP_AUTO_RELOAD"), default=False),
+        controllers_package=os.getenv(
+            "APP_CONTROLLERS_PACKAGE",
+            "app.api.controllers",
+        ),
+    )
+
+
+def _to_bool(value: str | None, *, default: bool) -> bool:
+    """把环境变量字符串转换为布尔值。"""
+    if value is None:
+        return default
+    return value.lower() in {"1", "true", "yes", "on"}

isanic/templates/full/app/core/logging.py

@@ -0,0 +1,11 @@
+import logging
+
+
+def configure_logging(debug: bool) -> logging.Logger:
+    """配置应用日志。"""
+    level = logging.DEBUG if debug else logging.INFO
+    logging.basicConfig(
+        level=level,
+        format="%(asctime)s %(levelname)s [%(name)s] %(message)s",
+    )
+    return logging.getLogger("{{ project_name }}")

isanic/templates/full/app/main.py

@@ -0,0 +1,14 @@
+from app.core.app import create_app
+from app.core.config import load_settings
+
+settings = load_settings()
+app = create_app(settings)
+
+
+if __name__ == "__main__":
+    app.run(
+        host=settings.host,
+        port=settings.port,
+        debug=settings.debug,
+        auto_reload=settings.auto_reload,
+    )

isanic/templates/full/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "{{ project_name }}"
+version = "0.1.0"
+description = "基于 iSanic-e 生成的 Sanic 后端项目"
+readme = "README.md"
+requires-python = ">=3.14,<3.15"
+dependencies = [
+    "isanic-e>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8,<10",
+    "sanic-testing>=24,<26",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]
+filterwarnings = [
+    "ignore::DeprecationWarning",
+]

isanic/templates/full/tests/test_framework.py

@@ -0,0 +1,98 @@
+from sanic import Sanic
+
+from app.core.app import create_app
+from app.core.config import Settings
+
+
+def make_app() -> Sanic:
+    """创建测试应用。"""
+    return create_app(Settings(app_name="{{ project_name }}Test"))
+
+
+def test_hello_route_is_registered() -> None:
+    """测试控制器方法自动注册为路由。"""
+    _, response = make_app().test_client.get("/hello/test")
+
+    assert response.status == 200
+    assert response.json == {
+        "code": 0,
+        "message": "success",
+        "data": {"message": "hello"},
+    }
+
+
+def test_json_body_is_validated_and_injected() -> None:
+    """测试 JSON 请求体会被校验并注入表单对象。"""
+    _, response = make_app().test_client.post(
+        "/login/submit",
+        json={"username": "alice", "password": "secret1"},
+    )
+
+    assert response.status == 200
+    assert response.json["data"] == {"token": "token-for-alice"}
+
+
+def test_form_data_is_validated_and_injected() -> None:
+    """测试 form-data 会被校验并注入表单对象。"""
+    _, response = make_app().test_client.post(
+        "/login/submit",
+        data={"username": "bob", "password": "secret2"},
+    )
+
+    assert response.status == 200
+    assert response.json["data"] == {"token": "token-for-bob"}
+
+
+def test_query_string_is_validated_and_injected() -> None:
+    """测试查询字符串会被校验并注入表单对象。"""
+    _, response = make_app().test_client.get("/users/list?page=2&size=20")
+
+    assert response.status == 200
+    assert response.json["data"] == {"page": 2, "size": 20}
+
+
+def test_validation_error_returns_422() -> None:
+    """测试表单校验失败会返回统一 422 响应。"""
+    _, response = make_app().test_client.post(
+        "/login/submit",
+        json={"username": "a", "password": "bad"},
+    )
+
+    assert response.status == 422
+    assert response.json["code"] == "VALIDATION_ERROR"
+    assert response.json["message"] == "请求参数校验失败"
+
+
+def test_app_error_returns_unified_response() -> None:
+    """测试业务异常会返回统一错误响应。"""
+    _, response = make_app().test_client.post(
+        "/login/submit",
+        json={"username": "disabled", "password": "secret1"},
+    )
+
+    assert response.status == 403
+    assert response.json == {
+        "code": "USER_DISABLED",
+        "message": "用户已被禁用",
+        "data": None,
+    }
+
+
+def test_http_response_is_not_wrapped_twice() -> None:
+    """测试 Sanic 原生响应不会被二次包装。"""
+    _, response = make_app().test_client.get("/users/raw")
+
+    assert response.status == 200
+    assert response.text == "raw response"
+
+
+def test_not_found_returns_unified_response() -> None:
+    """测试 404 会返回统一响应结构。"""
+    _, response = make_app().test_client.get("/missing")
+
+    assert response.status == 404
+    assert response.json == {
+        "code": "NOT_FOUND",
+        "message": "接口不存在",
+        "data": None,
+    }

isanic/validation.py

@@ -0,0 +1,109 @@
+import inspect
+from collections.abc import Callable
+from typing import Any, get_type_hints
+
+from pydantic import BaseModel, ValidationError
+from sanic import Request
+
+from isanic.exceptions import ValidationAppError
+
+BODY_METHODS = {"POST", "PUT", "PATCH"}
+QUERY_METHODS = {"GET", "DELETE"}
+
+
+class ValidationErrorResponse(BaseModel):
+    """参数校验错误响应数据。"""
+
+    field: str
+    message: str
+    type: str
+
+
+class FormBinding(BaseModel):
+    """控制器方法的表单绑定信息。"""
+
+    parameter_name: str
+    model_class: type[BaseModel]
+
+    model_config = {"arbitrary_types_allowed": True}
+
+
+def resolve_form_binding(handler: Callable[..., Any]) -> FormBinding | None:
+    """从控制器方法签名中解析唯一表单参数。"""
+    signature = inspect.signature(handler)
+    type_hints = get_type_hints(handler)
+    bindings: list[FormBinding] = []
+
+    for name, parameter in signature.parameters.items():
+        if name == "self":
+            continue
+
+        annotation = type_hints.get(name, parameter.annotation)
+        if _is_pydantic_model(annotation):
+            bindings.append(
+                FormBinding(parameter_name=name, model_class=annotation)
+            )
+
+    if len(bindings) > 1:
+        raise TypeError(f"{handler.__qualname__} 只允许声明一个表单模型参数")
+
+    return bindings[0] if bindings else None
+
+
+def build_form_model(request: Request, binding: FormBinding) -> BaseModel:
+    """按 HTTP 方法提取请求数据并构建表单模型。"""
+    payload = _extract_payload(request)
+    try:
+        return binding.model_class.model_validate(payload)
+    except ValidationError as exception:
+        raise ValidationAppError(_format_validation_errors(exception)) from exception
+
+
+def _extract_payload(request: Request) -> dict[str, Any]:
+    """从请求中提取待校验数据。"""
+    method = request.method.upper()
+    if method in QUERY_METHODS:
+        return _mapping_to_dict(request.args)
+    if method in BODY_METHODS:
+        if _is_json_request(request):
+            json_payload = request.json
+            if isinstance(json_payload, dict):
+                return json_payload
+        return _mapping_to_dict(request.form)
+    return {}
+
+
+def _mapping_to_dict(mapping: Any) -> dict[str, Any]:
+    """把 Sanic 的参数容器转换为普通字典。"""
+    data: dict[str, Any] = {}
+    for key, value in mapping.items():
+        if isinstance(value, list) and len(value) == 1:
+            data[key] = value[0]
+        else:
+            data[key] = value
+    return data
+
+
+def _format_validation_errors(error: ValidationError) -> list[dict[str, Any]]:
+    """格式化 Pydantic 校验错误，避免泄露内部对象。"""
+    errors: list[dict[str, Any]] = []
+    for item in error.errors():
+        errors.append(
+            ValidationErrorResponse(
+                field=".".join(str(part) for part in item["loc"]),
+                message=item["msg"],
+                type=item["type"],
+            ).model_dump(mode="json")
+        )
+    return errors
+
+
+def _is_json_request(request: Request) -> bool:
+    """判断请求体是否声明为 JSON。"""
+    content_type = request.headers.get("content-type", "")
+    return "application/json" in content_type or content_type.endswith("+json")
+
+
+def _is_pydantic_model(annotation: Any) -> bool:
+    """判断注解是否为 Pydantic 模型类型。"""
+    return inspect.isclass(annotation) and issubclass(annotation, BaseModel)

isanic_e-0.1.0.dist-info/METADATA

@@ -0,0 +1,83 @@
+Metadata-Version: 2.4
+Name: isanic-e
+Version: 0.1.0
+Summary: 基于 Sanic 的类型化表单验证后端脚手架
+Author: iSanic-e contributors
+License-Expression: MIT
+Keywords: sanic,scaffold,backend,pydantic,api
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: sanic<26,>=25.12
+Requires-Dist: pydantic<3,>=2.12
+Provides-Extra: dev
+Requires-Dist: build<2,>=1.3; extra == "dev"
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: sanic-testing<26,>=24; extra == "dev"
+
+# iSanic-e
+
+基于 Sanic 的类型化表单验证后端脚手架。
+
+安装后可以通过 `isanic init` 快速生成一个完整可运行的 Sanic 项目，内置：
+
+- 控制器自动路由注册
+- Pydantic v2 表单验证
+- 统一成功和错误响应
+- 全局异常处理
+- 示例控制器、表单模型和测试
+
+## 安装
+
+```bash
+python -m pip install isanic-e
+```
+
+## 初始化项目
+
+```bash
+isanic init demo
+cd demo
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m app.main
+```
+
+## 控制器示例
+
+```python
+from app.api.schemas.login import LoginForm
+from isanic import ApiController
+
+
+class Login(ApiController):
+    async def post_submit(self, form: LoginForm) -> dict[str, str]:
+        return {"token": f"token-for-{form.username}"}
+```
+
+上面的代码会自动注册为：
+
+```text
+POST /login/submit
+```
+
+## 业务异常
+
+```python
+from isanic import AppError
+
+raise AppError("用户已被禁用", code="USER_DISABLED", status_code=403)
+```
+
+返回：
+
+```json
+{
+  "code": "USER_DISABLED",
+  "message": "用户已被禁用",
+  "data": null
+}
+```

isanic_e-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+isanic/__init__.py,sha256=_KKUYCSyWSjvQg6pyQNQczqpY34L6TdG1ZRwj54ve4I,517
+isanic/cli.py,sha256=2VTLBZf_r6Z0hMF8nIUMhRMFbOgsxhpRqTFtVlnt6qo,3290
+isanic/controller.py,sha256=ZwsJAzi7F5Xl5vaYtGuEQ1_pVurZJIdXEMY22FBi3SE,251
+isanic/exceptions.py,sha256=zNIel7zo4jdkNFmumnZek_Zh24cVKMWfimqNbCrrO2U,722
+isanic/handlers.py,sha256=wtZn7HIJzjUnO-3nbG2UfWBj0Zm6wnewynzOSTpSo9A,1393
+isanic/response.py,sha256=WdwEsIa7wL-13H_aQb9SEpTJ2lXMJ4xk_1miGjJbLP4,1688
+isanic/routing.py,sha256=8mPtcpcezdNbrTDXKXR9IuQDXUXCnBF6vGbDzh6HRPY,4953
+isanic/validation.py,sha256=lW7UXMEeJakQt4Np5szJpuYSylGNlnpMRJkIx34r6jc,3477
+isanic/templates/full/README.md,sha256=PlPtrqRQPqCY4aSOFs54FSxEaSisH5nxml_Q4yer0T8,372
+isanic/templates/full/_gitignore,sha256=VEpZj8AVS1Jj7L4t5fMvDoCcRty0xtaLwRw8z_BLR50,96
+isanic/templates/full/pyproject.toml,sha256=xqguWRTtp9BT9TXxf5K_k2B7EbD_o_6XfghIqTXRP7w,429
+isanic/templates/full/app/__init__.py,sha256=Yaz3I3KhEaNU8pe3CaxbGGE8muahrBdEyjM_-f3IAMU,19
+isanic/templates/full/app/main.py,sha256=oQt1YZBANzDIPFBMJZigzkQo2kk3DLFqC_8Vvg_C-8g,309
+isanic/templates/full/app/api/__init__.py,sha256=GCsz5xYzX_C-LGmtCb7rDyf9mZ2bYs7GOFz_i2Q72OQ,25
+isanic/templates/full/app/api/controllers/__init__.py,sha256=jjmBoZ_iVbx0qvzTXAUmsTJkOSrlgsPgTihUZNc_8Vs,22
+isanic/templates/full/app/api/controllers/hello.py,sha256=Tcu7ASWnOcnRMxoQcKp7npjy6VNMryPiXLTxoBjFWy0,207
+isanic/templates/full/app/api/controllers/login.py,sha256=ogDqRDoMZbukzslnQtLuhtUmRx4U9W84BpVjUksfpBQ,850
+isanic/templates/full/app/api/schemas/__init__.py,sha256=dZZXYoGlODR6RPfUIKBvM62I_09fMQV2PYU8-WAffrs,34
+isanic/templates/full/app/api/schemas/login.py,sha256=KboH3nkTGGvK5IP8OIO200zM8p6ScYXfcLJqemTLQJk,366
+isanic/templates/full/app/common/__init__.py,sha256=3fOMnVI76p00PrhurOlJMhHjYm_ACnAPf6Uqmcf0X18,25
+isanic/templates/full/app/core/__init__.py,sha256=MXnmEcYKBE7S2YhZNRfssuhKx3eoXjhrAst-P5c2syA,40
+isanic/templates/full/app/core/app.py,sha256=1u9ofJsUSosHB_rrLYVQFF1iV7XIWr6IE1wOZk9pOOk,610
+isanic/templates/full/app/core/config.py,sha256=q3_9ylkCoCrvpI05KpVWDrfR1qwBcc3C2VcPoi8noao,1070
+isanic/templates/full/app/core/logging.py,sha256=SOmJffHfdUYawXStdQxVl55W1BFV0aTNA1HqT2PCNv8,326
+isanic/templates/full/tests/test_framework.py,sha256=EiHxEN5nMcKAFC7BByTepdIze-C2HQMDo1Fnn7pnH9o,2966
+isanic_e-0.1.0.dist-info/METADATA,sha256=k0DQ7UauMvS9e3LUQdo7E5lvO-HvjqeBKU9HV_tS1ls,1841
+isanic_e-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+isanic_e-0.1.0.dist-info/entry_points.txt,sha256=B9pd2m2FJRvpHj07RKmH3trQ4y4bEyDNw7Je8BwjP_0,43
+isanic_e-0.1.0.dist-info/top_level.txt,sha256=GIj82zBo7gefv-Q1mwCGtEGOoO7QXnNVAWiM7G-8SNs,7
+isanic_e-0.1.0.dist-info/RECORD,,

isanic_e-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

isanic_e-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+isanic = isanic.cli:main

isanic_e-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+isanic