MonkeyCode文档自动生成：从代码到文档的一键转换
引言
在软件开发中，有一句广为流传的调侃："程序员最讨厌的两件事：1. 别人的代码不写文档；2. 自己写文档。"
文档维护是软件开发中公认的"老大难"问题：
- 写文档耗时：一个中等规模的API可能需要2-3小时撰写完整文档
- 更新不及时：代码改了但文档没跟上，导致"文档与实际不符"
- 格式不统一：不同开发者写的文档风格差异大
- 语言障碍：英文技术文档对非英语母语开发者不友好
- 多格式需求：同一份内容需要输出Markdown、HTML、PDF、OpenAPI等多种格式
MonkeyCode的智能文档生成能力，能够直接从源代码、注释和类型定义中，自动生成高质量的技术文档。本文将全面介绍MonkeyCode的文档自动化能力。
一、文档痛点全景图
┌─────────────────────────────────────────────────────────────┐
│ 技术文档 痛点矩阵 │
│ │
│ 📝 API文档 │
│ ├── 手写OpenAPI/Swagger规范费时 │
│ ├── 接口变更后文档滞后 │
│ ├── 参数说明/返回值/错误码遗漏 │
│ ├── 示例代码与实际不一致 │
│ └── 多版本API文档管理混乱 │
│ │
│ 📖 代码注释/README │
│ ├── README过时（"最后更新于2023年"） │
│ ├── 架构文档缺失或过于简略 │
│ ├── 新人上手没有引导文档 │
│ ├── 变更日志(Changelog)不完整 │
│ └── 部署文档步骤遗漏 │
│ │
│ 📚 内部知识库 │
│ ├── 技术决策记录(ADR)散落在各处 │
│ ├── 最佳实践没有沉淀 │
│ ├── 故障排查经验未文档化 │
│ ├── 团队编码规范靠口头传达 │
│ └── Onboarding材料陈旧 │
│ │
│ 🌐 多语言文档 │
│ ├── 国际化项目需要多语言支持 │
│ ├── 手工翻译成本高且质量不稳定 │
│ ├── 术语翻译不统一 │
│ └── 版本同步困难 │
└─────────────────────────────────────────────────────────────┘
二、MonkeyCode文档生成核心能力
2.1 支持的文档类型
document_types_supported:
# === API文档 ===
api_docs:
- name: "OpenAPI 3.0 / Swagger"
source: "代码注解 + 类型推断"
output_format: ["YAML", "JSON", "HTML(交互式)"]
features:
- "自动识别REST端点"
- "参数类型推导"
- "请求/响应示例生成"
- "认证方式标注"
- name: "GraphQL Schema"
source: "Resolver + Type定义"
output_format: ["SDL", "Markdown"]
- name: "gRPC / Protobuf"
source: ".proto文件 + Service定义"
output_format: [".proto", "Markdown", "HTML"]
- name: "异步消息接口"
source: "消息生产者/消费者代码"
output_format: ["AsyncAPI", "Markdown"]
# === 代码级文档 ===
code_docs:
- name: "JSDoc / TSDoc"
source: "TypeScript/JavaScript源码"
auto_generate:
- "函数签名"
- "参数说明"
- "返回值类型"
- "使用示例"
- "@throws/@deprecated标注"
- name: "JavaDoc / KDoc"
source: "Java/Kotlin源码"
auto_generate:
- "类/方法/字段说明"
- "@param @return @throws"
- "@since @version @author"
- "使用示例(@example)"
- name: "Docstring (Python)"
source: "Python源码(Google/NumPy/Sphinx风格)"
auto_generate:
- "Args/Returns/Raises"
- "Attributes"
- "Examples(含doctest)"
- "Notes/See Also"
# === 项目级文档 ===
project_docs:
- name: "README.md"
sections:
- "项目简介 + Badge"
- "功能特性列表"
- "快速开始(Quick Start)"
- "安装指南"
- "使用示例"
- "API概览"
- "目录结构说明"
- "开发指南"
- "贡献指南(CONTRIBUTING)"
- "许可证"
- name: "架构设计文档(ADR)"
format: "结构化决策记录"
template:
- "背景(Context)"
- "决策(Decision)"
- "状态(Status)"
- "后果(Consequences)"
- "替代方案(Alternatives)"
- name: "Changelog"
style: "Keep a Changelog(语义化版本)"
auto_detect:
- "Breaking Changes"
- "New Features"
- "Bug Fixes"
- "Deprecations"
2.2 从代码到文档——实战演示
场景一：自动生成API文档
"""
MonkeyCode 自动分析以下Python代码并生成完整的API文档
"""
from dataclasses import dataclass, field
from datetime import datetime
from typing import Optional, List, Generic, TypeVar
from enum import Enum
class OrderStatus(str, Enum):
"""订单状态枚举"""
PENDING = "pending" # 待支付
PAID = "paid" # 已支付
SHIPPED = "shipped" # 已发货
COMPLETED = "completed" # 已完成
CANCELLED = "cancelled" # 已取消
REFUNDING = "refunding" # 退款中
@dataclass
class CreateOrderRequest:
"""
创建订单请求体
Attributes:
user_id: 用户唯一标识符
items: 订单商品列表
shipping_address: 收货地址信息
coupon_code: 可选的优惠码
order_type: 订单类型（普通/秒杀/预售）
remark: 订单备注
Example:
>>> req = CreateOrderRequest(
... user_id="U10086",
... items=[OrderItem(sku_id="SKU001", quantity=2)],
... shipping_address=Address(...),
... )
"""
user_id: str
items: List['OrderItem']
shipping_address: 'Address'
coupon_code: Optional[str] = None
order_type: str = "NORMAL" # NORMAL | FLASH_SALE | PRE_SALE
remark: Optional[str] = None
@dataclass
class OrderItem:
"""订单商品项"""
sku_id: str # 商品SKU ID
quantity: int # 购买数量（>0）
price: Optional[float] = None # 单价（可选，系统取实时价格）
@dataclass
class Address:
"""收货地址"""
province: str
city: str
district: str
detail: str
receiver_name: str
receiver_phone: str # 手机号（脱敏存储）
@dataclass
class OrderResponse:
"""
创建订单响应体
MonkeyCode根据此数据类自动生成：
✅ OpenAPI Schema
✅ 字段说明表格
✅ JSON示例
✅ TypeScript类型定义
"""
order_id: str # 订单编号（格式：ORD+时间戳+随机数）
status: OrderStatus # 订单初始状态
total_amount: float # 订单总金额（单位：元，保留2位小数）
discount_amount: float # 优惠减免金额
payable_amount: float # 实付金额
items: List[OrderItem] # 订单商品明细
create_time: datetime # 创建时间
expire_time: datetime # 支付截止时间（30分钟后过期）
# MonkeyCode额外生成的计算字段
estimated_delivery: Optional[str] = field(
default=None,
metadata={"description": "预计送达时间，格式：YYYY-MM-DD"}
)
class OrderService:
"""
订单服务 —— 核心业务逻辑层
MonkeyCode AI Doc Generator 分析此类后自动生成：
┌─────────────────────────────────────┐
│ 📄 OpenAPI 3.0 规范（自动生成） │
├─────────────────────────────────────┤
│ POST /api/v1/orders │
│ 创建订单 │
│ │
│ Request Body: │
│ CreateOrderRequest (见上方) │
│ │
│ Responses: │
│ 201: OrderResponse │
│ 400: ErrorResponse │
│ - INVALID_ITEM (商品无效) │
│ - INSUFFICIENT_STOCK (库存不足)│
│ - COUPON_EXPIRED (优惠券过期) │
│ 409: ErrorResponse │
│ - ORDER_LIMIT_EXCEEDED │
│ 500: InternalErrorResponse │
│ │
│ Authentication: Bearer Token │
│ Rate Limit: 100 req/min │
└─────────────────────────────────────┘
"""
def __init__(self, db, cache, mq):
"""
初始化订单服务
Args:
db: 数据库会话实例
cache: Redis缓存客户端
mq: 消息队列生产者
"""
self.db = db
self.cache = cache
self.mq = mq
async def create_order(self, request: CreateOrderRequest) -> OrderResponse:
"""
创建新订单
这是订单服务的核心方法，执行以下流程：
1. 参数校验（用户存在性、商品有效性）
2. 库存预扣减（调用库存服务）
3. 优惠核销（如有优惠券）
4. 金额计算（商品总价 - 优惠 - 积分抵扣）
5. 持久化订单记录
6. 发送订单创建事件（供下游消费）
Args:
request: 创建订单请求对象
Returns:
OrderResponse: 包含完整订单信息的响应对象
Raises:
ValidationError: 当请求参数校验失败时
- USER_NOT_FOUND: 用户不存在
- ITEM_INVALID: 商品无效或已下架
- QUANTITY_INVALID: 数量必须大于0
BusinessError: 当业务规则校验失败时
- INSUFFICIENT_STOCK: 库存不足
- COUPON_INVALID: 优惠券不可用
- ORDER_LIMIT_DAILY: 超出日下单限制
Example:
>>> service = OrderService(db_session, redis_client, kafka_producer)
>>> response = await service.create_order(CreateOrderRequest(
... user_id="U10086",
... items=[OrderItem(sku_id="SKU001", quantity=2)],
... shipping_address=Address(
... province="北京市", city="北京市",
... district="朝阳区", detail="建国路88号",
... receiver_name="张三", receiver_phone="138****1234"
... ),
... ))
>>> print(response.order_id)
'ORD20250622143052ABC123'
Note:
此方法是幂等的——相同的请求+idempotency_key不会重复创建订单。
建议客户端实现重试机制时携带幂等键。
See Also:
- `cancel_order()`: 取消已创建的订单
- `query_order()`: 查询订单详情
- `OrderSagaOrchestrator`: 分布式事务编排器
"""
# MonkeyCode 注：以下是实际的业务逻辑代码
# 文档生成器会提取上述docstring中的结构化信息
...
MonkeyCode自动生成的文档输出
<!-- MonkeyCode 自动生成的 API 文档 -->
# 📚 订单服务 API 文档
> **自动生成时间**: 2025-06-22 14:35:00
> **源代码版本**: main@a3f7c2e
> **生成工具**: MonkeyCode v4.2.1 DocGen Engine
---
## 目录
- [概述](#概述)
- [快速开始](#快速开始)
- [API 接口](#api-接口)
- [创建订单](#创建订单-post)
- [查询订单](#查询订单-get)
- [取消订单](#取消订单-delete)
- [数据模型](#数据模型)
- [错误码参考](#错误码参考)
- [变更历史](#变更历史)
---
## 概述
订单服务负责处理电商平台的核心交易流程，包括订单创建、支付对接、物流触发等。服务采用**事件驱动架构**，通过Kafka消息队列与库存、支付、积分、物流等服务解耦。
### 核心特性
| 特性 | 描述 |
|------|------|
| 幂等性创建 | 支持基于Idempotency-Key的防重复提交 |
| 库存预扣 | 创建订单时预扣库存，超时自动释放 |
| 优惠核销 | 支持满减券、折扣券、免邮券 |
| 分布式事务 | 通过Saga模式保证最终一致性 |
| 异步通知 | 订单状态变更通过事件实时推送 |
---
## 快速开始
### 前置条件
- Python 3.11+
- 已配置的服务注册中心地址
- 有效的Bearer Token
### 认证方式
所有API请求需要在Header中携带访问令牌：
Authorization: Bearer <your_token_here>
---
## API 接口
### 创建订单 `POST /api/v1/orders`
创建一个新的购物订单。
#### 请求参数
**Headers**
| 参数名 | 必填 | 类型 | 说明 |
|--------|------|------|------|
| `Authorization` | 是 | string | Bearer Token |
| `X-Idempotency-Key` | 否 | string | 幂等键（推荐传入） |
| `Content-Type` | 是 | string | 必须为 `application/json` |
**Body (CreateOrderRequest)**
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `user_id` | string | 是 | - | 用户唯一标识符 |
| `items` | array[OrderItem] | 是 | - | 商品列表（至少1项） |
| `shipping_address` | Address | 是 | - | 收货地址 |
| `coupon_code` | string | 否 | null | 优惠码 |
| `order_type` | string | 否 | `"NORMAL"` | NORMAL / FLASH_SALE / PRE_SALE |
| `remark` | string | 否 | null | 订单备注 |
**OrderItem 对象**
| 字段 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| `sku_id` | string | 是 | - | 商品SKU ID |
| `quantity` | integer | 是 | - | 购买数量（≥1） |
| `price` | number | 否 | null | 单价（不传则取实时价） |
**Address 对象**
| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `province` | string | 是 | 省/直辖市 |
| `city` | string | 是 | 市 |
| `district` | string | 是 | 区/县 |
| `detail` | string | 是 | 详细地址 |
| `receiver_name` | string | is | 收货人姓名 |
| `receiver_phone` | string | is | 收货人手机号 |
#### 请求示例
```bash
curl -X POST https://api.example.com/api/v1/orders \
-H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
-H "X-Idempotency-Key: uniq-order-key-20250622" \
-H "Content-Type: application/json" \
-d '{
"user_id": "U10086",
"items": [
{"sku_id": "SKU001", "quantity": 2},
{"sku_id": "SKU042", "quantity": 1}
],
"shipping_address": {
"province": "北京市",
"city": "北京市",
"district": "朝阳区",
"detail": "建国路88号SOHO现代城A座",
"receiver_name": "张三",
"receiver_phone": "138****1234"
},
"coupon_code": "SAVE20JUN",
"order_type": "NORMAL",
"remark": "尽快发货"
}'
响应参数
201 Created — 成功
| 字段 | 类型 | 说明 |
|---|---|---|
order_id |
string | 订单编号 |
status |
string | 订单状态（固定为 "pending"） |
total_amount |
number | 商品总金额（元） |
discount_amount |
number | 优惠减免金额 |
payable_amount |
number | 实付金额 |
items |
array | 订单商品明细 |
create_time |
string(datetime) | 创建时间（ISO 8601） |
expire_time |
string(datetime) | 支付截止时间 |
estimated_delivery |
string(date) | 预计送达日期 |
响应示例
{
"code": 0,
"message": "success",
"data": {
"order_id": "ORD20250622143500A7B8C9D",
"status": "pending",
"total_amount": 299.00,
"discount_amount": 20.00,
"payable_amount": 279.00,
"items": [
{"sku_id": "SKU001", "quantity": 2, "price": 99.50},
{"sku_id": "SKU042", "quantity": 1, "price": 100.00}
],
"create_time": "2025-06-22T14:35:00+08:00",
"expire_time": "2025-06-22T15:05:00+08:00",
"estimated_delivery": "2025-06-25"
}
}
错误响应
| HTTP Code | Error Code | 说明 | 解决方案 |
|---|---|---|---|
| 400 | INVALID_ITEM |
商品无效或已下架 | 检查sku_id是否正确 |
| 400 | QUANTITY_INVALID |
数量必须大于0 | 检查quantity字段 |
| 409 | INSUFFICIENT_STOCK |
库存不足 | 减少购买数量或等待补货 |
| 409 | COUPON_EXPIRED |
优惠券已过期 | 更换有效优惠券 |
| 429 | ORDER_LIMIT_DAILY |
超出日下单限制 | 稍后重试 |
| 401 | UNAUTHORIZED |
未授权 | 检查Token是否有效 |
| 500 | INTERNAL_ERROR |
服务内部错误 | 联系技术支持 |
数据模型
OrderStatus 枚举
| 值 | 说明 | 允许的状态流转 |
|---|---|---|
pending |
待支付 | → paid → shipped → completed |
| → cancelled | ||
| → refunding (部分场景) | ||
paid |
已支付 | → shipped → completed |
| → refunding | ||
shipped |
已发货 | → completed |
| → refunding | ||
completed |
已完成 | （终态） |
cancelled |
已取消 | （终态） |
refunding |
退款中 | → cancelled (退款完成) |
ER 关系图（MonkeyCode自动生成）
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ orders │ │ order_items │ │ users │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ PK order_id │───┐ │ PK id │ │ PK user_id │
│ FK user_id │ ├──│ FK order_id │◀──┐ │ name │
│ status │ │ │ FK sku_id │ ├──│ phone │
│ total_amount │ │ │ quantity │ │ └──────────────┘
│ created_at │ │ │ unit_price │ │
└──────────────┘ │ └──────────────┘ │
│ │
▼ ▼
┌──────────────┐ ┌──────────────┐
│ skus │ │ coupons │
├──────────────┤ ├──────────────┤
│ PK sku_id │ │ PK code │
│ name │ │ discount │
│ price │ │ expires_at│
│ stock │ └──────────────┘
└──────────────┘
### 2.3 README自动生成
```markdown
<!-- MonkeyCode 为整个项目自动生成的 README.md -->
# 🐵 monkeycode-order-service
<p align="center">
<img src="https://img.shields.io/badge/version-2.3.1-blue.svg" alt="Version">
<img src="https://img.shields.io/badge/python-3.11%2B-green.svg" alt="Python">
<img src="https://img.shields.io/badge/license-Apache%202.0-orange.svg" alt="License">
<img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build">
</p>
<p align="center">
<strong>电商订单微服务 —— 基于 MonkeyCode 辅助开发的高性能订单系统</strong>
</p>
---
## ✨ 功能特性
- 🔒 **幂等订单创建** — 基于Idempotency-Key的防重复提交
- 📦 **库存预扣机制** — 创建即锁定，超时自动释放
- 🎫 **多类型优惠支持** — 满减/折扣/免邮/积分抵扣
- 🔄 **分布式事务** — Saga模式保证最终一致性
- ⚡ **高性能** — QPS 10,000+，P99 < 50ms
- 📊 **可观测性** — 全链路追踪 + Prometheus指标
## 🚀 快速开始
### 环境要求
- Python >= 3.11
- PostgreSQL >= 14
- Redis >= 7.0
- Kafka >= 3.5
### 安装
\`\`\`bash
git clone https://github.com/company/order-service.git
cd order-service
pip install -r requirements.txt
cp .env.example .env
# 编辑 .env 配置数据库连接等信息
\`\`\`
### 运行
\`\`\`bash
# 开发模式
python -m uvicorn app.main:app --reload --port 8080
# 或使用 Docker Compose
docker-compose up -d
\`\`\`
### Docker部署
\`\`\`bash
docker build -t order-service:latest .
docker run -d \
--name order-service \
-p 8080:8080 \
--env-file .env \
order-service:latest
\`\`\`
## 📁 项目结构
\`\`\`
order-service/
├── app/
│ ├── api/ # REST API 层
│ │ ├── v1/
│ │ │ ├── endpoints/ # 端点定义
│ │ │ └── schemas.py # 请求/响应模型
│ │ └── dependencies.py # 公共依赖注入
│ ├── services/ # 业务逻辑层
│ │ ├── order_service.py
│ │ ├── payment_service.py
│ │ └── inventory_client.py
│ ├── models/ # 数据模型
│ ├── repositories/ # 数据访问层
│ ├── core/ # 核心配置
│ │ ├── config.py
│ │ ├── security.py
│ │ └── events.py
│ └── utils/ # 工具函数
├── tests/ # 测试用例
│ ├── unit/
│ ├── integration/
│ └── e2e/
├── docs/ # 自动生成的文档
│ ├── api/ # API文档
│ └── architecture/ # 架构文档
├── docker/
│ ├── Dockerfile
│ └── docker-compose.yml
├── k8s/ # Kubernetes部署清单
├── scripts/ # 运维脚本
├── pyproject.toml
└── README.md ← 你正在阅读的这个文件！
\`\`\`
## 📡 API 文档
启动服务后访问：
- **Swagger UI**: http://localhost:8080/docs
- **ReDoc**: http://localhost:8080/redoc
- **OpenAPI JSON**: http://localhost:8080/openapi.json
## 🧪 测试
\`\`\`bash
# 运行全部测试
pytest
# 只运行单元测试
pytest tests/unit/
# 生成覆盖率报告
pytest --cov=app --cov-report=html
\`\`\`
## 📈 性能基准
| 指标 | 值 |
|------|-----|
| QPS (单实例) | ~12,000 |
| P50 延迟 | 12ms |
| P99 延迟 | 45ms |
| 启动时间 | < 3s |
| 内存占用 | ~180MB |
## 🤝 贡献
欢迎贡献代码！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细流程。
## 📄 许可证
本项目基于 [Apache License 2.0](LICENSE) 开源。
## 🙏 致谢
- [MonkeyCode](https://monkeycode.ai) — 本项目的AI编程助手
- [FastAPI](https://fastapi.tiangolo.com/) — Web框架
- [SQLAlchemy](https://www.sqlalchemy.org/) — ORM框架
三、CI/CD中文档自动化流水线
# MonkeyCode 文档自动生成 CI 配置
# .github/workflows/auto-docs.yml
name: Auto Documentation Generation
on:
push:
branches: [main]
pull_request:
branches: [main]
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # 获取完整Git历史
- name: Set up Python
uses: actions/setup-python@v5
with:
python-version: '3.12'
- name: Install MonkeyCode CLI
run: pip install monkeycode-cli>=4.2.0
# === 1. 生成API文档 ===
- name: Generate API Docs (OpenAPI)
run: |
monkeycode docs generate-api \
--source ./src \
--output ./docs/api \
--format openapi,json,html,markdown \
--include-private false \
--lang zh-CN
# === 2. 生成README ===
- name: Generate README
run: |
monkeycode docs generate-readme \
--project-root . \
--output ./README.md \
--template tech-blog \
--include-sections quickstart,architecture,api,contributing,license \
--badge-style flat-square
# === 3. 生成变更日志 ===
- name: Generate Changelog
run: |
monkeycode docs changelog \
--since-last-tag \
--style keepachangelog \
--output ./CHANGELOG.md
# === 4. 生成架构文档 ===
- name: Generate Architecture Diagrams
run: |
monkeycode docs architecture \
--source ./src \
--output ./docs/architecture \
--diagrams component,sequence,er,class
# === 5. 检测文档与代码的一致性 ===
- name: Check Doc-Code Consistency
run: |
monkeycode docs check-consistency \
--docs ./docs \
--source ./src \
--fail-on stale-docs,missing-examples,broken-links
# === 6. 提交文档变更 ===
- name: Commit Generated Docs
if: github.ref == 'refs/heads/main'
run: |
git config --local user.email "docs-bot@company.com"
git config --local user.name "Docs Bot"
git add docs/ README.md CHANGELOG.md
git diff --cached --quiet || git commit -m "📝 docs: auto-generated documentation [skip ci]"
git push
四、效果对比
| 维度 | 手工编写 | MonkeyCode自动生成 | 提升 |
|---|---|---|---|
| API文档编写时间 | 3-4小时/模块 | < 1分钟 | 200x↑ |
| 文档覆盖率 | 约40%（主要接口） | 100%（全部公开接口） | 150%↑ |
| 代码-文档一致性 | 约60%（经常滞后） | 100%（每次构建自动更新） | 67%↑ |
| README维护频率 | 月均更新1次 | 每次提交自动更新 | ∞ |
| 新人Onboarding时间 | 平均2周 | 平均3天 | -78% |
| 多语言文档成本 | 需专职翻译 | AI一键翻译+术语校准 | -90% |
五、最佳实践建议
5.1 让MonkeyCode生成更好文档的编码习惯
# ✅ 好的习惯：MonkeyCode能从中提取丰富信息
def calculate_discount(
order_total: Decimal,
coupon_code: Optional[str] = None,
user_level: str = "normal"
) -> DiscountResult:
"""
计算订单优惠金额。
支持多种优惠叠加规则：
1. 会员折扣（按用户等级）
2. 优惠券（满减/折扣/免邮）
3. 活动优惠（限时/限量）
4. 积分抵扣
优惠叠加优先级：活动 > 优惠券 > 会员折扣 > 积分抵扣
同类优惠不叠加，取最优值。
Args:
order_total: 订单原始总金额（不含运费），必须 ≥ 0
coupon_code: 优惠码，可选。传None表示不使用优惠券。
格式：6-16位字母数字组合。
user_level: 用户等级，影响会员折扣比例。
可选值："bronze"(无折扣), "silver"(95折),
"gold"(9折), "platinum"(85折)
Returns:
DiscountResult: 包含各项优惠明细和最终优惠结果的数据类。
- original_amount: 原始金额
- discount_items: 各项优惠明细列表
- total_discount: 总优惠金额
- final_amount: 优惠后金额
Raises:
ValueError:
- 当 order_total < 0 时
- 当 coupon_code 格式不合法时
- 当 user_level 不在允许值范围内时
CouponExpiredError: 当优惠券已过期时
CouponUsedError: 当优惠券已被使用时
Example:
>>> result = calculate_discount(
... order_total=Decimal("299.00"),
... coupon_code="SAVE20JUN",
... user_level="gold"
... )
>>> print(result.final_amount)
Decimal("249.15")
# 计算：299 * 0.9(金卡) - 20(优惠券) = 249.15
Note:
此函数不会修改数据库中的优惠券状态。
优惠券的实际核销应在订单支付成功后由PaymentService处理。
See Also:
- `CouponService.validate_coupon()`: 优惠券有效性验证
- `UserLevelService.get_user_level()`: 获取用户等级
- `DiscountResult`: 返回值数据类的详细定义
Todo:
- 支持跨品类满减（如：服饰+数码满500减50）
- 支持阶梯优惠（满100减10，满200减30）
Since: version 2.1.0
Author: @zhangsan (订单组)
"""
...
# ❌ 差的习惯：MonkeyCode几乎无法提取有用信息
def calc(t, c=None, l="n"):
"""计算优惠"""
# 大量业务逻辑...
result = some_complex_calculation(t, c, l)
return result
六、总结
MonkeyCode让"写文档"从负担变成副产品——当你按照良好规范编写代码和注释时，文档就已经自动生成了。
核心价值：
- 效率提升200倍：API文档从3小时缩短到1分钟
- 100%覆盖：所有公开接口都有文档
- 永远最新：每次代码提交自动更新文档
- 多格式输出：一份源码同时产出Markdown/HTML/PDF/OpenAPI
- 多语言支持：AI翻译保持术语一致性
下一篇预告：《MonkeyCode测试用例生成：提升测试覆盖率的新范式》
浙公网安备 33010602011771号