thin-wrappers
Encapsulates infrastructure SDKs behind minimal domain-aligned interfaces. Use when accessing any external infrastructure to keep SDK usage contained, testing simple, and changes easy.
- License 许可
- Unlicense
- 所属仓库
- saski/arnesto
- 最近更新
- 2026-11-12
- Stars
- ★ 6
- Forks
- 0
01 前言 Front Matter
- name
- thin-wrappers
- description
- Encapsulates infrastructure SDKs behind minimal domain-aligned interfaces. Use when accessing any external infrastructure to keep SDK usage contained, testing simple, and changes easy.
02 资源文件 3
- 参考文档references/cache-example.md4.5 KB
- 参考文档references/queue-example.md8.0 KB
- 参考文档references/storage-example.md9.4 KB
03 SKILL.md 正文
STARTER_CHARACTER = 🏗️
Thin Infrastructure Wrappers
Core Principle
Minimize the API surface area: expose only what you use today, in your domain's language. The wrapper should be significantly smaller than the SDK it wraps.
When to Apply
Apply thin wrappers when:
- Direct SDK usage spreads across the codebase
- Infrastructure concerns leak into business logic
- Testing requires mocking third-party libraries directly
- Switching providers or versions creates ripple effects
- SDK types and concepts appear in domain code
Skip when:
- The SDK is already minimal and domain-aligned
- Usage is isolated to a single boundary class
- The abstraction cost exceeds the coupling cost
Design Process
1. Identify Usage Patterns
Analyze existing SDK usage across the codebase:
- Find all import statements for the SDK
- Catalog which SDK methods are actually used
- Group usage by purpose (read, write, delete, etc.)
- Apply the 80% rule: focus on covering the most common operations first
2. Design Minimal Interface
Create an interface exposing only what's needed:
- Use domain terminology, not SDK terminology
- Expose operations, not SDK objects or types
- Keep method signatures simple and focused
- Prevent SDK types from escaping the wrapper
Anti-pattern: Exposing entire SDK "just in case"
Example transformation:
- SDK:
cache.set(key, value, ex=ttl, nx=True) - Wrapper:
cache.set_if_not_exists(key, value, ttl)
3. Choose Implementation Pattern
Two-layer approach (most common):
- Thin wrapper: Direct SDK encapsulation, minimal logic
- Domain class: Business logic using the wrapper
Use when business logic needs to be separated from infrastructure.
Single-class approach:
- Combine wrapper and domain logic in one class
Use when wrapper logic is minimal and business logic is simple.
4. Implement with Domain Language
Align method names and parameters with domain concepts:
publish_order_created(order_id, customer_id)notpublish(topic, message)fetch_user_profile(user_id)notget(bucket, key)store_uploaded_file(file_id, content)notput_object(params)
Gradual Refactoring
Migrate existing code incrementally:
- Create wrapper for 80% case: Start with most common usage patterns
- Replace one usage site at a time: Incremental, safe changes
- Measure progress: Track remaining direct SDK calls
- Refine interface: Adjust based on actual migration experience
- Complete migration: Handle remaining edge cases
Each step should be independently committable and testable.
Integration with Architecture
Thin wrappers naturally map to the adapter layer in hexagonal/clean architecture, implementing domain-defined ports.
Testing
Thin wrappers enable simple test doubles — no mocking libraries needed. See examples for test double implementations.
Anti-Patterns
Exposing SDK Types: Don't let SDK classes or enums leak through the wrapper boundary. Transform them into domain types.
Premature Abstraction: Don't create wrappers for single-use SDKs. Wait until usage patterns emerge.
Over-Engineering: Don't add configuration, features, or flexibility beyond current needs. Simple is better.
Generic Wrappers: Don't create DatabaseWrapper or QueueWrapper with every possible method. Expose only what the application uses.
Pass-Through Methods: Don't just rename SDK methods without adding domain meaning. Each wrapper method should represent a domain operation.
Examples
See reference implementations for common infrastructure types:
- Cache/Redis: references/cache-example.md
- Queue/Messaging: references/queue-example.md
- Storage/S3: references/storage-example.md
These illustrate the principles. Consider what fits your context.
04 同仓库更多 Skills
visualize
Use /visualize for creating compact charts, diagrams, or other visuals inline as part of the conversation itself. It chooses among Markdown tables, Mermaid, inline HTML, and other supported in-transcript forms. Use Canvas for durable artifacts outside the transcript that users may revisit, refine, or share.
update-cursor-settings
Modify Cursor/VSCode user settings in settings.json. Use when you want to change editor settings, preferences, configuration, themes, font size, tab size, format on save, auto save, keybindings, or any settings.json values.
update-cli-config
View and modify Cursor CLI configuration settings in ~/.cursor/cli-config.json. Use when the user wants to change CLI settings, configure permissions, switch approval mode, enable vim mode, toggle display options, configure sandbox, or manage any CLI preferences.
statusline
Configure a custom status line in the CLI. Use when the user mentions status line, statusline, statusLine, CLI status bar, prompt footer customization, or wants to add session context above the prompt.
split-to-prs
Split current work into small reviewable PRs. Use when the user asks to split a chat, set of changes, branch, or PR.
shell
Runs the rest of a /shell request as a literal shell command. Use only when the user explicitly invokes /shell and wants the following text executed directly in the terminal.