# 日志导入与查询服务:综合项目 这是Python专题的教学项目,供25~36篇实践与独立验收使用。它不接触生产系统,运行示例仅监听127.0.0.1。 ## 实现范围 - Pydantic输入契约:最多64条、明确时区、限定等级、拒绝额外字段。 - ASGI请求体上限:JSON解析前检查字节数,含分块请求。 - SQLAlchemy/SQLite:版本1建表、版本2新增查询索引;连接池2个连接、无overflow。 - 原子幂等:租户+操作键唯一,规范化输入摘要;重复请求返回原结果,换内容409。 - 有界导入队列:默认4个等待槽位、单消费者;超限503;HTTP超时504不撤销已接收操作。 - 请求ID和JSON结构日志:不记录令牌/请求体;查询绑定租户;全局指标仅管理员可读。 - lifespan启动/关闭:停止接收、等待队列、回收任务、关闭存储。 设计边界:队列在内存,不保证进程崩溃后未提交任务恢复;已提交操作的幂等记录持久化。单进程设计不能凭加workers获得全局队列上限;横向扩展要引入共享任务协议。当前令牌配置是教学用静态映射,不是完整身份平台。SQLite实验不证明PostgreSQL隔离或迁移行为。正常关闭不强制终止正在执行的数据库线程;硬停止由外部进程托管约定。 ## 安装与运行 在完整CPython3.13或3.14环境运行。依赖精确版本和锁文件由本轮实际验证后写入;不得把嵌入版当pip环境。 ```powershell # 在项目目录运行,隔离环境不要提交。 python -m venv .venv & .venv/Scripts/python.exe -m pip install -r requirements.lock.txt & .venv/Scripts/python.exe -m pip install --no-deps -e . # 本机教学令牌,生产部署必须用安全生成/分发的密钥。 $env:LOG_API_TOKEN = 'replace-with-a-local-teaching-token' $env:LOG_DATABASE = Join-Path (Get-Location) 'logs.sqlite' & .venv/Scripts/python.exe -m uvicorn log_capstone.app:app_factory --factory --host 127.0.0.1 --port 8088 --limit-concurrency 16 --timeout-keep-alive 2 ``` 用另一个终端发送请求: ```powershell $headers = @{'Authorization'='Bearer replace-with-a-local-teaching-token'; 'Idempotency-Key'='demo-1'} $body = '{"records":[{"source":"demo","timestamp":"2026-10-29T00:00:00Z","level":"INFO","message":"hello"}]}' Invoke-RestMethod -Uri http://127.0.0.1:8088/imports -Method Post -Headers $headers -ContentType application/json -Body $body # 同键、同内容第二次请求应返回同一个operation_id,不新增记录。 Invoke-RestMethod -Uri http://127.0.0.1:8088/imports -Method Post -Headers $headers -ContentType application/json -Body $body Invoke-RestMethod -Uri http://127.0.0.1:8088/records -Headers $headers ``` 本地CLI使用相同数据格式:将上述JSON保存为batch.json,再运行: ```powershell & .venv/Scripts/log-capstone.exe batch.json --database logs.sqlite --key cli-1 ``` Linux使用`.venv/bin/python`和`.venv/bin/log-capstone`;Linux命令须在目标环境复验,本轮Windows记录不能证明Linux发布已通过。 ## 质量与交付检查 ```powershell & .venv/Scripts/python.exe -m pytest & .venv/Scripts/python.exe -m mypy src/log_capstone & .venv/Scripts/python.exe -m build --wheel ``` 在干净环境安装wheel,从源码树外运行模块与CLI,才能验证产物。不在源码目录用PYTHONPATH成功就宣称安装正确。根目录的`scripts/python-series/verify_capstone.py --python 安装wheel的解释器`会启动真实uvicorn loopback请求并验证产物来源。 行为测试包括:同键并发重试、跨租户隔离、异内容拒绝、时间标准化、请求上限、静态授权边界、等待超时后提交、后台失败传播、队列拒绝及关闭后任务回收。 ## 分阶段练习 |阶段|自己完成的变更|交付证据| |---|---|---| |工具与契约|新增日志格式解析器,保留UTC/长度/错误策略|坏输入矩阵、守恒断言、路径与配置边界。| |分层与测试|写符合Store Protocol的内存替身;解释它不能证明什么|业务测试和真实SQL集成测试分开。| |真实API|增添筛选接口,保持租户条件与有限分页|类型检查、契约测试、真实网络请求。| |持久化与幂等|新增可恢复变更,不破坏旧客户端重试|升级兼容、原请求结果、同键不同内容拒绝。| |资源治理|观察消费者阻塞时队列满;给出队列预算|接收/拒绝数量、等待阶段、关闭行为。| |观测与性能|给出CPU、分配或数据库等待候选并验证|同负载曲线、反证、优化复测;不凭单次测量报收益。| |安全与发布|审查授权、输入、密钥、备份及回滚|负例测试、依赖清单、兼容和恢复记录。| ## 综合验收规则 先独立完成任务,再阅读参考实现。评审输入可以换格式、换时区、改变租户、重放并发请求、延迟消费者或制造数据库锁;不得将根因提前写在考题里。 必须能回答:操作是否提交?谁持有资源?一个指标不足以推出什么?队列在哪里受限?进程硬退出后哪些任务能恢复?旧版本如何读取新数据?为什么取消HTTP等待不能当作撤销交易? 不使用固定QPS或覆盖率作为高级能力认证。声明机器、负载和预算,验证功能、资源、数据与兼容边界;任一核心安全或一致性关卡失败,都不能用其他高分抵消。