@wneng/create-keel 0.3.6 → 0.4.1

package/src/templates/server-python/files/config.py

@@ -0,0 +1,40 @@
+"""Application configuration via pydantic-settings.
+
+环境变量映射规则：
+  - 全部大写、`_` 分隔
+  - 嵌套字段用 `__` 分隔（pydantic-settings 默认）
+  - 例：APP_NAME / APP_VERSION / CORS_ALLOW_ORIGINS=http://localhost:5173,http://localhost:3000
+
+`.env` 文件由 pydantic-settings 自动加载（项目根目录）。
+"""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    """Runtime settings.
+
+    新增字段必须：
+      - 给默认值（不要让生产环境因缺一个变量启动崩溃）
+      - 同步更新根 `.env.example`（如启用 contracts-base fragment）
+      - 敏感字段（密钥、token）只能从环境变量读，绝不写默认值
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_name: str = Field(default="<%= it.options.projectName %>-server")
+    app_version: str = Field(default="0.1.0")
+
+    # CORS：逗号分隔字符串解析为列表
+    cors_allow_origins: list[str] = Field(
+        default_factory=lambda: ["http://localhost:5173", "http://localhost:3000"]
+    )
+
+
+settings = Settings()

package/src/templates/server-python/files/main.py

@@ -0,0 +1,62 @@
+"""<%= it.options.projectName %>-server entry point.
+
+Contract First：路由 / 请求体 / 响应体应当与 contracts/openapi/api.yaml 对齐。
+新增端点的工作流见根 AGENTS.md §6（变更分级）+ docs/governance/change-tiers.md：
+端点新增 / 字段新增是 Tier 3，必须先冻结 contracts/openapi/api.yaml 再写实现。
+"""
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from .config import settings
+
+
+@asynccontextmanager
+async def lifespan(_app: FastAPI) -> AsyncIterator[None]:
+    """启动 / 关闭钩子。
+
+    在这里做：
+      - 数据库连接池初始化（如启用 db）
+      - Elasticsearch 客户端初始化（如启用 db=elasticsearch）
+      - 后台任务启动
+    关闭时反向清理。
+    """
+    yield
+
+
+app = FastAPI(
+    title=settings.app_name,
+    version=settings.app_version,
+    description="Generated by @wneng/create-keel; implement per contracts/openapi/api.yaml.",
+    lifespan=lifespan,
+)
+
+# CORS — 默认放开本地前端开发常用端口；生产请通过环境变量收紧 allow_origins
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=settings.cors_allow_origins,
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+
+@app.get("/healthz", tags=["meta"])
+async def healthz() -> dict[str, str]:
+    """Liveness 探针。
+
+    部署时由 Kubernetes / Docker Compose 周期性调用；返回非 200 即视为不健康。
+    """
+    return {"status": "ok"}
+
+
+@app.get("/", tags=["meta"])
+async def root() -> dict[str, str]:
+    return {
+        "name": settings.app_name,
+        "version": settings.app_version,
+        "docs": "/docs",
+    }

package/src/templates/server-python/files/pyproject.toml

@@ -2,13 +2,20 @@
 name = "<%= it.options.projectName %>-server"
 version = "0.1.0"
 requires-python = ">=3.11"
-dependencies = []
+dependencies = [
+  "fastapi==0.115.5",
+  "uvicorn[standard]==0.32.0",
+  "pydantic==2.9.2",
+  "pydantic-settings==2.6.1",
+]
 
 [project.optional-dependencies]
 dev = [
   "ruff>=0.6.8",
   "mypy>=1.11.0",
   "pytest>=8.3.0",
+  "pytest-asyncio>=0.24.0",
+  "httpx>=0.27.0",
   "pip-audit>=2.7.0",
 ]
 
@@ -47,3 +54,9 @@ exclude = ["generated", ".venv"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+asyncio_mode = "auto"
+
+# 显式声明应用包，避免 setuptools 把 generated/ 误认为顶层包导致 build error
+[tool.setuptools.packages.find]
+include = ["app*"]
+exclude = ["tests*", "generated*"]

package/src/templates/server-python/files/test_healthz.py

@@ -0,0 +1,36 @@
+"""Smoke test for the healthz endpoint.
+
+CI 跑 `pytest -q` 时会运行；端到端验证：
+  - FastAPI app 能 import（语法、依赖、配置都对）
+  - lifespan 钩子能起、能落
+  - /healthz 返回 200 + {"status": "ok"}
+
+新加端点应在 tests/ 下补对应测试；契约级断言（响应 schema 一致性）由
+contracts/tests/contracts/ 下的契约测试覆盖，不在这里重复。
+"""
+
+import pytest
+from httpx import ASGITransport, AsyncClient
+
+from app.main import app
+
+
+@pytest.mark.asyncio
+async def test_healthz_returns_ok() -> None:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/healthz")
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+@pytest.mark.asyncio
+async def test_root_returns_metadata() -> None:
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        response = await client.get("/")
+    assert response.status_code == 200
+    body = response.json()
+    assert body["name"].endswith("-server")
+    assert body["version"] == "0.1.0"
+    assert body["docs"] == "/docs"

package/src/templates/server-python/fragment.yaml

@@ -1,5 +1,5 @@
 name: server-python
-version: 1.0.0
+version: 1.1.0
 appliesWhen:
   backend: python
 priority: 30
@@ -12,6 +12,15 @@ files:
     render: true
   - from: files/app-init.py
     to: server/app/__init__.py
+    render: true
+  - from: files/main.py
+    to: server/app/main.py
+    render: true
+  - from: files/config.py
+    to: server/app/config.py
+    render: true
+  - from: files/test_healthz.py
+    to: server/tests/test_healthz.py
     render: false
   - from: files/generated-gitkeep
     to: server/generated/.gitkeep