example-framework-skill

Example Framework 技能

一个完整示例，演示 Claude Code 技能中正确的自包含模式。

适用场景：使用 Example Framework 构建应用——涵盖设置、模式、测试和部署。

---

概览

此技能演示了自包含技能开发的正确方法：

✅ 自包含：内联所有必要内容，可独立使用 ✅ 无依赖项：不使用指向其他技能的相对路径 ✅ 完整示例：提供可运行的代码，而非片段 ✅ 优雅降级：说明可选增强功能，但不要求使用 ✅ 适合扁平化部署：适用于任何目录结构

---

快速入门

安装

# Install framework
pip install example-framework

# Create new project
example-framework init my-project
cd my-project

# Install dependencies
pip install -r requirements.txt

# Run development server
example-framework dev

最简示例（自包含）

"""
Minimal Example Framework application.
Self-contained - no external skill dependencies.
"""
from example_framework import App, route

app = App()

@route("/")
def home():
    """Homepage route."""
    return {"message": "Hello, World!"}

@route("/users/{user_id}")
def get_user(user_id: int):
    """Get user by ID."""
    return {
        "id": user_id,
        "username": f"user_{user_id}"
    }

if __name__ == "__main__":
    # Development server
    app.run(host="0.0.0.0", port=8000, debug=True)

运行：

python app.py
# Visit: http://localhost:8000

---

核心模式

1. 应用设置（自包含）

完整设置模式——无外部依赖项：

from example_framework import App, Config
from example_framework.middleware import CORSMiddleware, LoggingMiddleware

# Configuration
config = Config(
    DEBUG=True,
    SECRET_KEY="your-secret-key-here",
    DATABASE_URL="sqlite:///./app.db"
)

# Application instance
app = App(config=config)

# Middleware
app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"]
)

app.add_middleware(LoggingMiddleware)

# Health check endpoint
@app.route("/health")
def health_check():
    """Health check endpoint."""
    return {"status": "healthy"}

2. 数据库集成（自包含）

基本数据库模式——以内联方式提供，确保自包含：

from example_framework import Database
from contextlib import contextmanager

# Database configuration
db = Database("sqlite:///./app.db")

@contextmanager
def get_db_session():
    """
    Database session context manager.

    Usage:
        with get_db_session() as session:
            users = session.query(User).all()
    """
    session = db.create_session()
    try:
        yield session
        session.commit()
    except Exception:
        session.rollback()
        raise
    finally:
        session.close()

# Model example
class User(db.Model):
    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    username = db.Column(db.String(80), unique=True, nullable=False)
    email = db.Column(db.String(120), unique=True, nullable=False)

    def to_dict(self):
        """Convert to dictionary."""
        return {
            "id": self.id,
            "username": self.username,
            "email": self.email
        }

# CRUD operations
@app.route("/users", methods=["POST"])
def create_user(data):
    """Create new user."""
    with get_db_session() as session:
        user = User(
            username=data["username"],
            email=data["email"]
        )
        session.add(user)
        return user.to_dict(), 201

@app.route("/users/{user_id}")
def get_user(user_id: int):
    """Get user by ID."""
    with get_db_session() as session:
        user = session.query(User).filter_by(id=user_id).first()
        if not user:
            return {"error": "User not found"}, 404
        return user.to_dict()

3. 测试模式（自包含）

基本测试模式——以内联方式提供，遵循测试最佳实践：

"""
Test suite for Example Framework application.
Self-contained testing patterns - no external skill dependencies.
"""
import pytest
from example_framework.testing import TestClient

# Test client fixture
@pytest.fixture
def client():
    """Create test client."""
    return TestClient(app)

# Database fixture
@pytest.fixture
def db_session():
    """Create test database session."""
    db.create_all()
    session = db.create_session()
    yield session
    session.close()
    db.drop_all()

# Test examples
def test_home_route(client):
    """Test homepage returns correct response."""
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello, World!"}

def test_create_user(client, db_session):
    """Test user creation."""
    response = client.post("/users", json={
        "username": "testuser",
        "email": "[email protected]"
    })
    assert response.status_code == 201
    data = response.json()
    assert data["username"] == "testuser"
    assert data["email"] == "[email protected]"

def test_get_user(client, db_session):
    """Test get user by ID."""
    # Create user
    user = User(username="testuser", email="[email protected]")
    db_session.add(user)
    db_session.commit()

    # Get user
    response = client.get(f"/users/{user.id}")
    assert response.status_code == 200
    assert response.json()["username"] == "testuser"

def test_user_not_found(client):
    """Test 404 for nonexistent user."""
    response = client.get("/users/999")
    assert response.status_code == 404

运行测试：

pytest tests/

---

错误处理

标准错误处理程序模式（自包含）

from example_framework import HTTPException

@app.error_handler(404)
def not_found_handler(error):
    """Handle 404 errors."""
    return {
        "error": "Not Found",
        "message": str(error)
    }, 404

@app.error_handler(500)
def server_error_handler(error):
    """Handle 500 errors."""
    return {
        "error": "Internal Server Error",
        "message": "An unexpected error occurred"
    }, 500

@app.error_handler(HTTPException)
def http_exception_handler(error):
    """Handle HTTP exceptions."""
    return {
        "error": error.name,
        "message": error.description
    }, error.status_code

# Custom validation error
class ValidationError(Exception):
    """Validation error."""
    pass

@app.error_handler(ValidationError)
def validation_error_handler(error):
    """Handle validation errors."""
    return {
        "error": "Validation Error",
        "message": str(error)
    }, 400

---

最佳实践

1. 配置管理

# environment-based configuration
import os
from example_framework import Config

class DevelopmentConfig(Config):
    DEBUG = True
    DATABASE_URL = "sqlite:///./dev.db"

class ProductionConfig(Config):
    DEBUG = False
    DATABASE_URL = os.getenv("DATABASE_URL")
    SECRET_KEY = os.getenv("SECRET_KEY")

# Load config based on environment
env = os.getenv("ENV", "development")
config = DevelopmentConfig() if env == "development" else ProductionConfig()

app = App(config=config)

2. 依赖注入

# Dependency injection pattern
from example_framework import Depends

def get_current_user(token: str = Depends("Authorization")):
    """Get current user from token."""
    # Token validation logic
    user_id = validate_token(token)
    return User.query.get(user_id)

@app.route("/profile")
def get_profile(user: User = Depends(get_current_user)):
    """Get current user profile."""
    return user.to_dict()

3. 请求验证

from example_framework import validate_request

# Request schema
user_schema = {
    "username": {"type": "string", "minLength": 3, "maxLength": 80},
    "email": {"type": "string", "format": "email"},
    "age": {"type": "integer", "minimum": 0}
}

@app.route("/users", methods=["POST"])
@validate_request(user_schema)
def create_user(data):
    """Create user with validated data."""
    # Data is already validated
    user = User(**data)
    db.session.add(user)
    db.session.commit()
    return user.to_dict(), 201

---

部署

生产环境部署（自包含）

"""
Production deployment configuration.
Self-contained - all necessary patterns included.
"""

# 1. Use production server (e.g., gunicorn)
# requirements.txt:
# gunicorn>=20.1.0

# 2. Production configuration
import os

class ProductionConfig:
    DEBUG = False
    TESTING = False
    SECRET_KEY = os.getenv("SECRET_KEY")
    DATABASE_URL = os.getenv("DATABASE_URL")
    ALLOWED_HOSTS = os.getenv("ALLOWED_HOSTS", "").split(",")

app = App(config=ProductionConfig())

# 3. Run with gunicorn
# gunicorn -w 4 -b 0.0.0.0:8000 app:app

# 4. Environment variables (.env)
# SECRET_KEY=your-production-secret-key
# DATABASE_URL=postgresql://user:pass@localhost/dbname
# ALLOWED_HOSTS=example.com,www.example.com

---

配套技能

使用此技能时，可考虑以下相关技能（如果已部署）：

• pytest-patterns：高级测试模式和夹具

  • 适用场景：通过参数化构建全面的测试套件
  • 集成方式：增强上文所示的基本测试模式
  • 状态：可选——此技能已包含基本测试模式

• database-orm-patterns：高级 ORM 模式和优化

  • 适用场景：复杂查询、关系和性能调优
  • 集成方式：在上文所示的基本数据库模式上扩展
  • 状态：可选——此技能已包含基本 CRUD 模式

• api-security：身份验证、授权和安全最佳实践

  • 适用场景：适用于生产环境的安全实现
  • 集成方式：为路由添加安全层
  • 状态：建议用于生产环境——上文已展示基本示例

• deployment-patterns：Docker、CI/CD、监控和扩展

  • 适用场景：生产环境部署和运维
  • 集成方式：部署策略和工具
  • 状态：可选——上文已展示基本部署

注意：所有配套技能均可独立部署。没有它们，此技能也可正常使用。

---

常见问题

❌ 不要：使用相对导入

# DON'T DO THIS
from ..other_skill.patterns import setup

✅ 应该：使用自包含模式

# Include pattern directly
def setup():
    """Setup pattern (self-contained)."""
    # Implementation here
    pass

❌ 不要：依赖外部技能

# DON'T DO THIS
# This requires pytest-patterns skill
from skills.pytest_patterns import fixture_factory

✅ 应该：以内联方式提供必要模式

# Include essential pattern
def fixture_factory(name, default=None):
    """Fixture factory pattern (inlined)."""
    @pytest.fixture
    def _fixture():
        return default
    _fixture.__name__ = name
    return _fixture

---

渐进式披露

如需了解更多高级主题，请参阅 references/ 目录：

• references/advanced-patterns.md：高级框架模式
• references/performance.md：性能优化
• references/api-reference.md：完整 API 文档

注意：主 SKILL.md 内容完整，可独立使用。参考资料提供可选的深入说明。

---

资源

官方文档：

• Example Framework 文档：https://example-framework.readthedocs.io
• API 参考：https://example-framework.readthedocs.io/api
• 社区：https://github.com/example-framework/community

相关技术：

• Python：https://docs.python.org
• SQLite：https://www.sqlite.org
• Pytest：https://docs.pytest.org

---

概述

此技能展示了自包含的技能开发：

✅ 完整：内联包含所有必要模式
✅ 独立：无需依赖其他技能即可运行
✅ 经过测试：已通过独立测试
✅ 可部署：适用于扁平目录结构
✅ 灵活：说明可选增强功能，但不要求使用

将此内容用作模板，以创建新技能。

---

版本：1.0.0
最后更新：2025-11-30
自包含性：✅ 完全符合要求