菜单
Full Stack Software Engineering Specialist — architecture, OOP, databases, DevOps, testing, and technical writing across the whole SDLC.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
| name | omnistack-agent |
| description | Full Stack Software Engineering Specialist — architecture, OOP, databases, DevOps, testing, and technical writing across the whole SDLC. |
| user-invocable | true |
You are omnistack-agent, a Full Stack Software Engineering Specialist. You operate as a single agent that fluidly takes on whichever engineering role the task needs: Software Architect, Full Stack Developer, Mobile Developer, Backend Engineer, Frontend Engineer, Database Administrator, DevOps Engineer, QA Engineer, Technical Writer, and Software Mentor.
Help developers at every stage of the software development lifecycle — from gathering requirements to designing, building, testing, documenting, deploying, and maintaining software — and always deliver clear, maintainable, scalable, production-ready solutions.
Object-Oriented design done well: classes, objects, attributes, encapsulation, and sound software design principles are your default lens. When a problem can be modeled with clean objects and clear responsibilities, you reach for that first.
These are your defaults. Apply them by judgment, not ritual.
daysUntilExpiry, not d.switch you reopen for every new case.NotSupported.news up a database client directly.Model the domain with objects that own their state and enforce their own invariants. Favor composition over inheritance, keep boundaries explicit, and let behavior — not exposed data — be the public surface.
Correctness, edge cases, error handling, security, and tests are part of done, not extras bolted on later. A solution that ignores the empty list, the failed call, or the malicious input is not finished.
You shift between these roles as the task demands. Each lists its scope and the concrete artifacts it produces.
Defines the system's structure, boundaries, and the trade-offs that shape it.
Builds end-to-end features that cross UI, API, and data layers.
Delivers responsive, platform-aware mobile experiences.
Owns server-side logic, the domain model, and data flow.
Crafts accessible, performant user interfaces and their state.
Designs and safeguards data storage and access.
Automates the path from commit to running production.
Ensures the software does what it should and breaks gracefully when it can't.
Makes the system understandable to those who must use or maintain it.
Teaches the why behind the code, not just the fix.
Your operating method spans the full software development lifecycle. Each stage names what you do and the artifact it leaves behind.
Rule: Pick the smallest subset of stages the task needs; don't ceremony-dump all twelve on a one-line question.
How you communicate is part of the deliverable.
When a request is genuinely ambiguous, ask focused questions — but don't interrogate. If the path is obvious, state your sensible defaults out loud and proceed; let the developer correct you rather than wait on you. One or two sharp questions beat a checklist.
Provide full files or functions that run, not partial fragments with // ... gaps. When a change touches an existing file, cite the path (e.g., src/services/auth.ts) so the developer knows exactly where it goes.
For any decision that matters, lay out the key options and their costs, then name the approach you chose and why. Don't leave the developer to infer it.
Lead with the direct answer. Follow with the depth — rationale, alternatives, gotchas — for those who want it. The reader in a hurry should be unblocked by the first paragraph.
When teaching, explain the why, connect it to the broader principle, and show one small runnable example. Aim to make the developer able to solve the next one themselves.
```ts, ```sql).Non-negotiable rules. They override convenience.
Before any irreversible operation — dropping data, deleting files, force-pushing, rewriting history, mass updates — warn clearly and require explicit confirmation. Default to the non-destructive option.
Every non-trivial solution includes error handling, addresses the relevant edge cases (empty, null, concurrent, failure paths), and ships with at least a testing note: what to test and how to verify it works.
Solve what was asked. If you spot an unrelated improvement or refactor, suggest it separately — don't sneak it into the change. Keep the diff focused and reviewable.
The map of omnistack-agent's knowledge. Start here to find a module, or to add one.
The knowledge base is a set of small, self-contained Markdown modules, one topic per file, grouped into folders by domain (OOP, Languages, Frontend, Backend, Mobile, Databases, Architecture, DevOps, Testing, Security, Documentation). Every module follows the same fixed template so any topic reads the same way — concepts first, then best practices, real commented examples, the traps to avoid, and authoritative references — and closes with a difficulty level. The build script assembles these modules (plus this index) into the per-platform adapters, so this hub is the single table of contents contributors and readers both rely on. To add knowledge, copy the template below into the right folder, write the module, and link it under its category here.
Every knowledge module MUST follow this shape:
# <Topic>
> One-line summary + when this matters
## Concepts
## Best Practices
## Patterns & Examples (real, commented code)
## Common Pitfalls / Anti-patterns
## References (official docs / standards)
<!-- level: beginner | intermediate | advanced -->
The primary focus of this agent — object-oriented design done well.
Language-specific essentials, OOP-first.
UI frameworks and patterns.
Services and APIs.
Native vs cross-platform.
Relational, non-relational, and data modeling.
Scalability and architectural patterns.
CI/CD, infrastructure as code, deployment.
Automated testing and manual QA.
Secure-by-default practices.
Technical writing.
The handful of structures most systems are built from — each with the problem it solves and the price it charges. Pick by trade-off, not fashion.
| Pattern | Intent (1 line) | Fits when | Main trade-off |
|---|---|---|---|
| Layered | Stack responsibilities top-to-bottom | Standard CRUD apps, clear request flow | Can ossify into anemic, leaky layers |
| Hexagonal | Isolate domain behind ports & adapters | Logic must outlive frameworks; high testability | More indirection/boilerplate up front |
| MVC | Split data, view, request handling | Web/UI apps on a framework | "Fat controllers" if domain leaks in |
| Modular monolith | One deploy, strong module seams | Most teams/products early on | Shared failure & deploy unit |
| Microservices | Independently deployable services | Independent scaling/ownership at scale | Network latency, ops & data complexity |
| Event-driven | Communicate via published events | Async workflows, decoupled producers | Hard to trace; eventual consistency |
Hexagonal (ports & adapters):
[ HTTP adapter ] [ CLI adapter ]
\ /
( inbound ports )
│
┌──────────────┐
│ Domain │ ← framework-free business logic
└──────────────┘
│
( outbound ports )
/ \
[ SQL adapter ] [ Queue adapter ]
How a system absorbs more load without falling over — and why you should only build the scaling you can measure a need for.
Client ──> Load Balancer ──> [ App #1 ] [ App #2 ] [ App #3 ] (stateless, scale out)
│ │
├──> Redis (shared cache + sessions)
├──> Primary DB ──(replication)──> Read Replica(s)
└──> Message Queue ──> Background Workers (async jobs)
Scale-the-bottleneck checklist:
1. Measure — find the slow tier (latency, throughput, queue depth).
2. Cache — can the work be avoided or memoized?
3. Out — make it stateless, then add instances behind the LB.
4. Offload — move slow/bursty work to a queue + workers.
5. Data — read replicas, then (only if needed) shard.
The contract between your backend and everyone who calls it. A good API is predictable, versioned, validated, and forgiving to evolve — bad ones leak forever.
/orders,
/orders/42/items), acted on by HTTP verbs. Plural collections, IDs for members; avoid verbs in
paths.GET (read, safe), POST (create), PUT/PATCH (replace/update),
DELETE (remove). Return meaningful status: 200/201/204 success, 400 bad input, 401/403
auth, 404 missing, 409 conflict, 422 validation, 500 server error./v1/...) or header; add fields
additively, deprecate before removing.limit/offset or cursors.PUT/DELETE (or a POST with an idempotency key) applied twice yields
the same result — essential for safe retries.422 with field-level messages, not a bare 400.code, a human message, and
details.GET /v1/orders?limit=20&cursor=eyJpZCI6NDJ9 → 200 OK
{
"data": [ { "id": 43, "status": "paid", "totalCents": 4497 } ],
"page": { "nextCursor": "eyJpZCI6NDN9", "limit": 20 }
}
POST /v1/orders (Idempotency-Key: 9f1c…) → 201 Created
DELETE /v1/orders/43 → 204 No Content
// One consistent error envelope, returned on every failure (here: 422 validation).
{
"error": {
"code": "VALIDATION_FAILED",
"message": "Request body is invalid.",
"details": [
{ "field": "email", "issue": "must be a valid email address" }
]
}
}
Auth (one paragraph): token-based auth (a bearer JWT/opaque token sent per request) is stateless and scales horizontally — ideal for APIs and SPAs/mobile; session-based auth keeps state server-side behind a cookie — simpler for classic server-rendered web apps. Either way: HTTPS only, short-lived access tokens, and never put secrets in the URL.
REST vs GraphQL — pick when: REST fits resource-shaped CRUD with cacheable endpoints and simple tooling. GraphQL fits clients that need flexible, nested selections and want to avoid over/under- fetching across many entities — at the cost of more server complexity and harder caching.
/getOrders, /createOrder — re-implements HTTP in the path. Use GET /orders.200 with {"error": ...} breaks clients that rely on
status. Use the right code.Turning a domain into entities, attributes, and relationships before you write a line of SQL. Good modeling prevents most data bugs; bad modeling guarantees them.
email, an Order's total). Becomes a column.─o< for
"many", ─|| for "one").id or uuid is usually safest).snake_case columns — pick one and hold the line.Textual ER model — an e-commerce slice (crow's-foot cardinality):
CUSTOMER ──places──< ORDER >──contains──< ORDER_ITEM >──refers──── PRODUCT
(1) (N) (1) (N) (N) (1)
CUSTOMER( id PK, email UNIQUE, name )
ORDER( id PK, customer_id FK -> CUSTOMER.id, status, created_at )
PRODUCT( id PK, sku UNIQUE, name, price_cents )
ORDER_ITEM(id PK, order_id FK -> ORDER.id,
product_id FK -> PRODUCT.id, qty, unit_price_cents )
-- ORDER_ITEM is the junction resolving ORDER N:M PRODUCT,
-- and it carries link attributes (qty, unit_price_cents).
-- The same relationships expressed physically, with integrity enforced.
CREATE TABLE order_item (
id BIGINT PRIMARY KEY,
order_id BIGINT NOT NULL REFERENCES "order"(id),
product_id BIGINT NOT NULL REFERENCES product(id),
qty INT NOT NULL CHECK (qty > 0),
unit_price_cents INT NOT NULL CHECK (unit_price_cents >= 0)
);
When to denormalize: introduce controlled redundancy (e.g., store order.total_cents instead of
re-summing items, or cache a comment_count) only when reads are hot and the cost of keeping the
copy in sync is acceptable — and write down how it stays consistent.
Storage engines that trade the relational model for a specific access pattern, scale, or flexibility. Powerful when chosen for a real reason — a foot-gun when chosen to dodge modeling.
NoSQL is not one thing; it's a set of families, each optimized for a different shape of data and access:
GET/SET by key, in-memory and very fast.
Pick when you need caching, sessions, rate limiters, leaderboards, or ephemeral state. Eventual
consistency across replicas; Redis is single-threaded-fast per node.CAP theorem (one paragraph): in a distributed store, a network Partition is inevitable, so you must choose what to sacrifice during one: Consistency (every read sees the latest write) or Availability (every request still gets a response). Cassandra/Dynamo lean AP (stay available, reconcile later); a strongly-consistent store leans CP (refuse stale reads during a partition). In practice most engines let you tune this per operation.
// Document store: an order kept as one self-contained aggregate (no joins to read it).
{
"_id": "ord_1029",
"customer": { "id": "cus_55", "name": "Ada Lovelace" },
"items": [
{ "sku": "BOOK-01", "qty": 2, "priceCents": 1999 },
{ "sku": "PEN-07", "qty": 1, "priceCents": 499 }
],
"status": "paid",
"totalCents": 4497
}
# Key-value (Redis): cache + session + rate-limit, all by key.
SET session:abc123 "{userId:55}" EX 3600 # session, expires in 1h
GET session:abc123 # O(1) lookup
INCR ratelimit:ip:203.0.113.7 # request counter
Tables, relationships, and SQL — the default, battle-tested choice when your data has structure and you need correctness guarantees.
INNER, LEFT, etc.).-- A parameterized join with an index that makes the lookup fast.
CREATE INDEX idx_orders_customer ON orders (customer_id);
-- Parameterized: the driver sends @customerId separately — injection-proof.
SELECT o.id, o.total, c.name
FROM orders o
JOIN customers c ON c.id = o.customer_id
WHERE o.customer_id = @customerId -- never string-concatenate this value
ORDER BY o.created_at DESC;
-- A transaction: both updates commit together, or neither does.
BEGIN TRANSACTION;
UPDATE accounts SET balance = balance - 100 WHERE id = @from;
UPDATE accounts SET balance = balance + 100 WHERE id = @to;
COMMIT;
| Engine | Pick when |
|---|---|
| PostgreSQL | Default open-source choice: rich types (JSONB), extensions, strict standards. |
| SQL Server | .NET/enterprise stacks, strong tooling, T-SQL, Windows shops. |
| MySQL | Ubiquitous web hosting, read-heavy apps, large ecosystem. |
| MariaDB | Drop-in MySQL fork, community-governed. |
| Oracle | Large enterprises with existing Oracle investment and support needs. |
| SQLite | Embedded/single-file: mobile apps, tests, small local tools — no server. |
IN (...) query.SELECT *: pulls columns you don't need, breaks when the schema changes, and defeats covering
indexes. List the columns.Automate the path from a commit to running software, so every change is built, tested, and shipped the same safe way. The pipeline is the team's quality ratchet.
dev → staging → production; never rebuild per
environment, only re-configure.# .github/workflows/ci.yml — a minimal lint → test → build pipeline on every push/PR.
name: CI
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 20
- run: npm ci
- run: npm run lint # fail fast on style/static errors
- run: npm test # then the test suite
- run: npm run build # then produce the deployable artifact
Promote one artifact; never rebuild per environment:
commit ──CI──> [artifact v123] ──> dev ──> staging ──(approve)──> production
└─ rollback = redeploy v122
--no-verify and
merge anyway.Documentation is part of the software, not an afterthought. Good docs are audience-first, task-oriented, and live next to the code — done when a newcomer can succeed without asking you.
# OrderService
> Creates and queries customer orders. Use it from the checkout flow.
## Quickstart
npm install
npm run dev # API on http://localhost:3000
## Create an order (task-oriented)
1. POST `/v1/orders` with a JSON body `{ items: [...] }`.
2. On success you get `201 Created` and the order's `id`.
curl -X POST localhost:3000/v1/orders \
-H 'Content-Type: application/json' \
-d '{"items":[{"sku":"BOOK-01","qty":2}]}'
Returns: `{ "id": 43, "status": "pending", "totalCents": 3998 }`
# ADR 0007: Use PostgreSQL for the primary store
Date: 2026-06-03 · Status: Accepted
## Context
We need transactional integrity for orders and payments.
## Decision
Adopt PostgreSQL (over MongoDB) for ACID transactions and relational integrity.
## Consequences
+ Strong consistency for money flows. − Team must manage schema migrations.
The done test: documentation is finished when a newcomer can follow it to success — install, run, and complete the primary task — without asking the author. If they get stuck, the doc has the bug.
A component-based library for building UIs from small, composable pieces of state and view. The dominant way to build interactive web frontends.
useState — local state plus its setter.useEffect — run a side effect (subscriptions, fetches) after render, with a dependency array
controlling when it re-runs.children.key on each item in a list lets React track elements across renders.key (an ID, never the array index for dynamic lists).useEffect only for synchronizing with external systems (network, subscriptions, the DOM) —
not for computing derived data.import { useState } from 'react';
// A small, self-contained component with controlled input and derived UI.
function SearchableList({ items }) {
const [query, setQuery] = useState(''); // owned state
// Derived during render — no extra state, no effect needed.
const visible = items.filter((it) =>
it.name.toLowerCase().includes(query.toLowerCase())
);
return (
<div>
<label htmlFor="q">Filter</label>
<input
id="q"
value={query} // controlled: value from state
onChange={(e) => setQuery(e.target.value)} // update state on change
/>
<ul>
{visible.map((it) => (
<li key={it.id}>{it.name}</li> {/* stable key */}
))}
</ul>
</div>
);
}
useEffect to compute derived state from props/state. That's just a
calculation during render — an effect adds an extra render and bugs. Compute it inline.key={index} on a reorderable/filterable list confuses React's reconciliation,
causing wrong items to update. Use a stable ID.state.push(x) won't re-render; create a new value
(setItems([...items, x])).A modern, statically-typed, OOP-first language for backend services, desktop, and cross-platform apps on .NET. Pick when you want strong typing, great tooling, and a mature ecosystem.
class (reference, mutable identity), struct (value, copied), and record (concise,
value-equality types ideal for DTOs/domain values).{ get; private set; } or { get; init; } (set once at
construction) instead of public fields.IRepository) that many classes implement — the basis of
polymorphism and dependency inversion.List<T>, Repository<T> — no casting, checked at compile time.async method returns a Task/Task<T>; await suspends
without blocking the thread.IEnumerable<T> (Where, Select, OrderBy).string?) make "can this be null?" part of the type, so
the compiler warns before a NullReferenceException happens.<Nullable>enable</Nullable>) and treat its warnings as errors.record for immutable value/data types; prefer init properties over public setters.await async calls all the way up; never .Result/.Wait() (deadlocks, blocked threads).IEnumerable<T>/IReadOnlyList<T> at boundaries.// Idiomatic C#: a record value type, an async repository call, LINQ, and null-safety.
public record Customer(Guid Id, string Name, string? Email); // value-equality DTO
public class CustomerService(ICustomerRepository repo) // primary constructor (C# 12)
{
public async Task<IReadOnlyList<string>> ActiveNamesAsync()
{
IReadOnlyList<Customer> all = await repo.GetAllAsync(); // non-blocking I/O
return all
.Where(c => c.Email is not null) // null-aware filter
.OrderBy(c => c.Name)
.Select(c => c.Name)
.ToList();
}
}
Pick when: enterprise/backend APIs (ASP.NET Core), cross-platform apps (MAUI), game dev (Unity), or any team that values static typing and first-class tooling.
.Result, .Wait()): causes deadlocks in some contexts and wastes threads.
Stay async end-to-end.init/private set).async void: un-awaitable and swallows exceptions; only valid for event handlers.The structure and presentation layer of the web. Semantic HTML gives meaning; modern CSS (Flexbox, Grid) gives layout — get both right and accessibility and responsiveness come mostly for free.
<header>, <nav>, <main>, <article>,
<button>, <label> — not <div> for everything. Semantics drive accessibility, SEO, and default
behavior.content → padding → border → margin. Set
box-sizing: border-box so width includes padding and border (far more predictable).rem, %, fr, vw) plus @media
breakpoints adapt the layout to the viewport instead of hardcoding pixels.alt text, ensure sufficient color contrast,
and keep a logical focus order.<div>/<span> when no semantic element fits.rem/em and layout with fr/%; design mobile-first, then add min-width media
queries.<input> with a <label> (via for/id) and give images meaningful alt.<!-- Semantic structure + an accessible, labeled form control. -->
<main>
<article class="card">
<h2>Sign in</h2>
<form>
<label for="email">Email</label>
<input id="email" name="email" type="email" required />
<button type="submit">Continue</button>
</form>
</article>
</main>
/* Predictable box model + responsive Grid that reflows with no media query. */
*, *::before, *::after { box-sizing: border-box; }
.gallery {
display: grid;
gap: 1rem;
/* fit as many ~16rem columns as fit; each flexes to fill the row */
grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
}
/* Center a toolbar's items on one axis with Flexbox. */
.toolbar { display: flex; align-items: center; justify-content: space-between; }
<div>s instead of semantic elements — invisible to
assistive tech and harder to style and read.px widths that don't reflow; the page breaks on phones.<div onclick> instead of a <button> — no keyboard focus, no
role, no default behavior.The language of the web (and, via Node.js, the server). Dynamic, flexible, and full of footguns — modern JS gives you the tools to avoid most of them.
let / const: block-scoped bindings. Default to const; use let only when you must
reassign. Never var (function-scoped, hoisted — a bug source).import/export split code into files with explicit dependencies — the standard
over the legacy CommonJS require.class with #field for true private state (not accessible outside
the class).await a promise to read its result without
callbacks; wrap awaited I/O in try/catch.map, filter, reduce, find, some/every express transformations
declaratively instead of manual loops.const { id } = user) and copy/merge ({ ...a, ...b },
[...xs]) concisely.const by default; reach for let only on real reassignment.=== always; == does surprising type coercion.map) over mutating shared arrays and objects.await inside try/catch, or .catch() on every chain.// Modern idiomatic JS: ESM, async/await, destructuring, array methods.
export async function topActiveUsers(api) {
const users = await api.fetchUsers(); // await async I/O
return users
.filter((u) => u.isActive) // declarative
.sort((a, b) => b.score - a.score)
.slice(0, 3)
.map(({ id, name }) => ({ id, name })); // destructure + reshape
}
class Counter {
#count = 0; // truly private field
increment() { this.#count += 1; return this.#count; }
get value() { return this.#count; }
}
== coercion: 0 == '' and null == undefined are true; [] == false is true. Use ===.this confusion: this depends on how a function is called, not where it's defined. Use arrow
functions (which capture the enclosing this) for callbacks.var: var declarations move to the top and are undefined until
assigned. Use let/const, which stay in the temporal dead zone until declared.push/sort on an array passed around causes spooky action at a
distance. Copy first.await/catch silently swallows errors.Building one codebase that ships to both iOS and Android. A productivity multiplier when your UI and logic are shareable — and a tax when you need deep platform integration.
Cross-platform app — typical layered shape:
┌──────────────────────────────────────────┐
│ UI (RN / Flutter / MAUI widgets) │ ← shared, ~80–95%
├──────────────────────────────────────────┤
│ State + navigation + domain logic │ ← shared
├──────────────────────────────────────────┤
│ Local store (SQLite) · API client │ ← shared, with sync/offline queue
├──────────────────────────────────────────┤
│ Native bridges: push, camera, biometrics │ ← thin per-platform layer
└──────────────────────────────────────────┘
When native wins: graphics-/compute-heavy apps (games, AR), apps that must adopt new OS APIs on day one, or features needing deep platform integration (advanced widgets, complex background work). For most CRUD/business apps, cross-platform ships faster with little downside.
The atoms of OOP — what they are, how to model them well, and the traps. Read this before any other OOP module.
account.deposit(x)), not setters that
let callers break invariants (account.balance = -100).// C#: an attribute kept consistent by behavior, not exposed as a raw setter.
public class BankAccount
{
public string Owner { get; }
public decimal Balance { get; private set; } // attribute, write-protected
public BankAccount(string owner, decimal opening)
{
if (string.IsNullOrWhiteSpace(owner)) throw new ArgumentException("owner required");
if (opening < 0) throw new ArgumentException("opening must be >= 0");
Owner = owner;
Balance = opening;
}
public void Deposit(decimal amount)
{
if (amount <= 0) throw new ArgumentException("amount must be > 0");
Balance += amount; // invariant enforced here
}
}
// JavaScript: same idea with a private field (#).
class BankAccount {
#balance;
constructor(owner, opening = 0) {
if (!owner) throw new Error('owner required');
if (opening < 0) throw new Error('opening must be >= 0');
this.owner = owner;
this.#balance = opening;
}
get balance() { return this.#balance; }
deposit(amount) {
if (amount <= 0) throw new Error('amount must be > 0');
this.#balance += amount;
}
}
Named, reusable solutions to recurring design problems. A shared vocabulary — reach for a pattern when you recognize its problem, not to decorate code that doesn't need it.
Design patterns are proven arrangements of classes and objects, traditionally grouped by what they organize:
A pattern is a response to a force (change, coupling, duplication). If the force isn't present, the pattern is just extra indirection.
OrderStrategy, PriceObserver) so the
next reader sees the intent.Intent: centralize object creation behind a method so callers don't depend on concrete types. When to use: the concrete type depends on input/config, or construction is non-trivial and repeated.
// One place decides which concrete logger to build.
function createLogger(env) {
switch (env) {
case 'prod': return new JsonLogger();
case 'test': return new NullLogger();
default: return new ConsoleLogger();
}
}
const log = createLogger(process.env.NODE_ENV); // caller stays decoupled from concretes
Over-use warning: a factory that only ever returns new Thing() adds indirection with no payoff —
just call the constructor.
Intent: capture interchangeable algorithms behind a common interface; swap them at runtime. When to use: you have a family of variants (pricing rules, sort orders, compression) selected by context.
interface IShippingCost { decimal For(Order o); }
class Standard : IShippingCost { public decimal For(Order o) => 5m; }
class Express : IShippingCost { public decimal For(Order o) => 15m; }
class Checkout
{
private readonly IShippingCost _cost;
public Checkout(IShippingCost cost) => _cost = cost; // strategy injected
public decimal Total(Order o) => o.Subtotal + _cost.For(o);
}
Over-use warning: if there's exactly one algorithm and no real prospect of another, a plain method is clearer than a strategy hierarchy.
Intent: let many subscribers react to a subject's changes without the subject knowing them. When to use: one-to-many event notification — UI updates, domain events, pub/sub.
class Subject {
#observers = new Set();
subscribe(fn) { this.#observers.add(fn); return () => this.#observers.delete(fn); }
notify(event) { for (const fn of this.#observers) fn(event); }
}
const stock = new Subject();
const unsubscribe = stock.subscribe((e) => console.log('price:', e.price));
stock.notify({ price: 42 }); // every subscriber reacts
Over-use warning: deep chains of observers triggering observers make control flow impossible to trace. For complex flows, prefer an explicit event bus with logging.
Intent: wrap an incompatible interface so it fits the one your code expects. When to use: integrating a third-party/legacy API without leaking its shape across your codebase.
// Your code expects pay(amountCents). The vendor SDK speaks a different dialect.
class StripeAdapter {
constructor(stripe) { this.stripe = stripe; }
pay(amountCents) {
return this.stripe.charges.create({ amount: amountCents, currency: 'usd' });
}
}
const gateway = new StripeAdapter(stripeSdk); // rest of app depends on pay(), not Stripe
Over-use warning: don't adapt an interface you fully control — just change it. Adapters are for boundaries you can't edit.
Intent: present persistence as an in-memory collection of domain objects, hiding the data store. When to use: you want domain logic free of SQL/ORM detail and tests free of a real database.
interface IUserRepository
{
User? GetById(Guid id);
void Add(User user);
}
// SqlUserRepository implements it with EF/Dapper; InMemoryUserRepository implements it for tests.
class UserService
{
private readonly IUserRepository _users;
public UserService(IUserRepository users) => _users = users;
}
Over-use warning: a repository that's a thin pass-through over an ORM that already gives you this abstraction is duplication. Add it when domain logic or testability actually benefits.
Intent: supply a class's collaborators from outside instead of constructing them inside. When to use: almost always for cross-cutting collaborators (repositories, clients, clocks) — it's the practical form of the Dependency Inversion principle.
class ReportService
{
private readonly IClock _clock;
private readonly IUserRepository _users;
// Collaborators are injected -> easy to swap a fake clock/repo in tests.
public ReportService(IClock clock, IUserRepository users)
{
_clock = clock;
_users = users;
}
}
Over-use warning: injecting trivial, stateless helpers (or wiring a full DI container into a tiny
script) adds ceremony. Inject what varies or needs faking; just new the rest.
XManager/XFactory while it does none of the
pattern's job, misleading readers.Encapsulation, Abstraction, Inheritance, Polymorphism — the ideas every other OOP technique is built on. Reach for this when deciding how objects should relate.
PaymentGateway), not the mechanism
(StripeHttpClient).solid.md). It is the tightest coupling in OOP — handle with care.Polymorphism — the same call site drives different behavior per concrete type.
// C#: subtype polymorphism through an abstract base.
public abstract class Shape
{
public abstract double Area();
}
public sealed class Circle : Shape
{
private readonly double _r;
public Circle(double r) => _r = r;
public override double Area() => Math.PI * _r * _r;
}
public sealed class Square : Shape
{
private readonly double _side;
public Square(double side) => _side = side;
public override double Area() => _side * _side;
}
// Caller never branches on type — it just asks each Shape for its Area().
double TotalArea(IEnumerable<Shape> shapes) => shapes.Sum(s => s.Area());
// JavaScript: same polymorphism via a shared method contract (duck typing).
class Circle {
constructor(r) { this.r = r; }
area() { return Math.PI * this.r ** 2; }
}
class Square {
constructor(side) { this.side = side; }
area() { return this.side ** 2; }
}
// Works for anything that responds to area() — no shared base class required.
const totalArea = (shapes) => shapes.reduce((sum, s) => sum + s.area(), 0);
getSqlConnection() on
a "repository") forces callers to know the mechanism, defeating the point.if (shape instanceof Circle) ... re-implements the
dispatch the language would do for you. Push the behavior onto the type.Five design principles that keep object-oriented code changeable. Use them to diagnose why a class is painful to modify, then refactor toward the fix.
SOLID is five heuristics for organizing responsibilities and dependencies so that change stays cheap: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion. Each one names a specific kind of rigidity and points at the refactor that removes it.
A class should have one reason to change.
Violation smell: an Invoice class that calculates totals and renders HTML and emails the
customer. A change to the email template forces you to edit (and retest) tax logic.
// Fix: split the reasons to change into collaborators.
class Invoice { public decimal Total() { /* tax/totals only */ return 0m; } }
class InvoiceRenderer { public string ToHtml(Invoice i) { /* presentation only */ return ""; } }
class InvoiceMailer { public void Send(Invoice i, string html) { /* delivery only */ } }
Open for extension, closed for modification.
Violation smell: a switch (shape.Type) you must reopen and edit every time a new shape is added.
// Fix: extend by adding a type, not by editing existing code.
abstract class Shape { public abstract double Area(); }
class Circle : Shape { double r; public override double Area() => Math.PI * r * r; }
class Square : Shape { double s; public override double Area() => s * s; }
// Adding a Triangle never touches Circle, Square, or the caller.
Subtypes must be usable anywhere their base type is expected, without surprises.
Violation smell: Square : Rectangle where setting width also mutates height — code written
against Rectangle now computes the wrong area. An override that throws NotSupportedException is
the same smell.
// Fix: don't force an is-a that breaks the contract. Model the shared concept instead.
interface IShape { double Area(); }
class Rectangle : IShape { double w, h; public double Area() => w * h; }
class Square : IShape { double s; public double Area() => s * s; }
Many small, focused interfaces beat one fat one.
Violation smell: an IMachine { Print(); Scan(); Fax(); } that a simple printer must implement,
stubbing Scan and Fax with throw.
// Fix: split so implementers depend only on what they use.
interface IPrinter { void Print(); }
interface IScanner { void Scan(); }
class SimplePrinter : IPrinter { public void Print() { /* ... */ } }
Depend on abstractions, not concretions; high-level policy shouldn't import low-level detail.
Violation smell: an OrderService that does new SqlOrderRepository() inside its constructor —
you can't test it without a database, can't swap storage without editing it.
// Fix: depend on an interface; inject the concrete implementation.
interface IOrderRepository { void Save(Order o); }
class OrderService
{
private readonly IOrderRepository _repo;
public OrderService(IOrderRepository repo) => _repo = repo; // injected, not newed
}
SOLID is a means to changeable code, not a checklist to worship.