English summary: LSP is about behavioral honesty. If a subtype claims to replace the base type, callers must get the same guarantees without hidden preconditions, ignored props, or runtime surprises.
Resumo em português: LSP é sobre honestidade comportamental. Se um subtipo promete substituir o tipo base, o consumidor precisa receber as mesmas garantias sem precondições escondidas, props ignoradas ou surpresas em runtime.
Artigo Long-Form (Português)
Sumário
- O problema real que este princípio resolve
- A definição que importa na prática
- O que este princípio não é
- Como o problema nasce em produto e time
- Sinais de violação em code review
- Heurística de diagnóstico
- Exemplo ruim em React e TypeScript
- Exemplo melhor em React e TypeScript
- Exemplo em backend e arquitetura
- Estratégia de testes
- Observabilidade e métricas
- Checklist de refatoração
- Trade-offs honestos
- Anti-patterns comuns
- Perguntas de code review
- Plano 30-60-90 dias
- Caso composto e métricas
- ADR template
- FAQ
- Conclusão
- Referências
- #newshortarticle
1. O problema real que este princípio resolve
Quase todo time frontend já viveu a tentação do “link que parece botão”. A troca parece
simples: renderizar um <a> com as mesmas props do <button>. O problema aparece
depois, quando disabled deixa de ter efeito, type="submit" some do contrato e o
analytics passa a contar cliques que nunca deveriam acontecer. O componente continua
compilando, mas a promessa para o consumidor já foi quebrada.
É assim que violações de Liskov entram em produção: não como erro de sintaxe, mas como
mentira comportamental. O nome do componente continua confortável. Os tipos continuam
aparentemente corretos. O runtime, porém, entrega menos do que foi prometido.
LSP existe para impedir esse tipo de regressão silenciosa. O princípio obriga a tratar
contratos como acordos observáveis, não como herança cosmética. Se o consumidor precisa
aprender exceções escondidas para lidar com o subtipo, a substituição já falhou.
2. A definição que importa na prática
Barbara Liskov definiu o princípio em termos de substituição comportamental. O ponto
central não é “subclasse herda de classe”. O ponto central é que qualquer cliente
escrito para o contrato base deve continuar correto quando recebe uma implementação
substituta.
Em linguagem cotidiana, isso significa que o subtipo não pode introduzir precondições
novas, não pode enfraquecer garantias prometidas e não pode ignorar partes importantes
do contrato. Aceitar a mesma assinatura e entregar comportamento diferente é fraude
arquitetural.
No frontend, isso aparece quando um componente “compatível” ignora props sem avisar. No
backend, aparece quando uma implementação lança NotImplemented em um método que o
contrato base dizia existir. Nos dois casos, o tipo parece correto. O sistema, não.
3. O que este princípio não é
LSP não é defesa cega de herança. Na verdade, boa parte das violações nasce quando
herança é usada cedo demais. O princípio conversa melhor com contratos explícitos,
composition e unions honestas do que com hierarquias por hábito.
LSP também não é detalhe acadêmico. Sempre que QA encontra um caso em que um subtipo se
comporta de forma “quase igual, mas não exatamente”, o custo recai no time inteiro. O
consumidor passa a carregar conhecimento acidental sobre variações internas.
O princípio tampouco exige que todas as implementações sejam idênticas. Ele exige
equivalência de promessas. Um link e um botão podem divergir internamente, mas não podem
compartilhar API se as garantias essenciais diferem.
4. Como o problema nasce em produto e time
Em produto, violações de LSP costumam ser introduzidas para acelerar design systems. A
equipe quer reaproveitar estilos, então cria wrappers que “parecem” compatíveis. O
problema é que acessibilidade, foco, submit, disabled, navegação e eventos nem sempre
compartilham o mesmo contrato.
No backend, a mesma pressão aparece quando um serviço abstrato é estendido por
implementações que suportam apenas parte do comportamento. Um canal de notificação
aceita send, mas só funciona se threadTs existir. Um método de pagamento aceita
refund, mas na prática lança exceção para um gateway específico. A superfície pública
virou um contrato que ninguém consegue cumprir por completo.
LSP corrige isso obrigando o time a escolher entre dois caminhos saudáveis: ou todas as
implementações cumprem a promessa base, ou o contrato é redesenhado para tornar as
diferenças explícitas. O que não pode acontecer é esconder diferença relevante atrás da
mesma interface.
5. Sinais de violação em code review
- Props aceitas pela interface pública não têm efeito em certas variantes.
- Subtipos adicionam pré-condições novas que o consumidor não foi informado a cumprir.
- Métodos herdados lançam erro em runtime ou ignoram silenciosamente parte do input.
- Consumidores precisam usar
if, instanceof ou checagens ad hoc para descobrir se
podem confiar no contrato.
- Testes passam para o tipo base, mas quebram assim que a implementação alternativa
entra em cena.
6. Heurística de diagnóstico
A regra operacional para Liskov Substitution Principle é simples de lembrar: mesma
promessa, mesmo comportamento observável. A dificuldade está em transformar essa frase
em rotina de review. O caminho mais seguro é tratar diagnóstico como checklist
recorrente, não como insight esporádico de arquiteto.
- Escreva o contrato em termos de efeitos observáveis. O que o consumidor pode esperar
ao passar
disabled, onSubmit, refund ou close?
- Liste precondições do tipo base. Qualquer subtipo que exija mais do que isso já ameaça
a substituição.
- Liste pós-condições do tipo base. Qualquer implementação que entregue menos garantias
já quebrou o contrato.
- Rode testes de conformidade em cada implementação. Se você precisa adaptar a suíte
para cada subtipo, a API talvez esteja mentindo.
- Procure por parâmetros aceitos apenas para compatibilidade de assinatura. Esse é um
indicador clássico de contrato inchado ou mal desenhado.
Esse tipo de diagnóstico funciona porque desloca a conversa do gosto pessoal para
evidência observável. Em vez de “eu faria diferente”, o time passa a discutir blast
radius, atores de mudança, precondições explícitas e custo de teste.
7. Exemplo ruim em React e TypeScript
O exemplo abaixo concentra a dor principal em uma única superfície. Ele compila, ele
parece prático e exatamente por isso é perigoso. O problema não é o framework; é o
contrato acidental que se forma quando detalhes demais convivem na mesma peça.
type ButtonProps = React.ComponentProps<"button"> & {
tone?: "primary" | "ghost";
href?: string;
};
export function Button(props: ButtonProps) {
if (props.href) {
return <a className={`btn btn-${props.tone ?? "primary"}`} {...props} />;
}
return <button className={`btn btn-${props.tone ?? "primary"}`} {...props} />;
}
8. Exemplo melhor em React e TypeScript
A refatoração boa não tenta impressionar. Ela só cria a fronteira que faltava. No caso
de Liskov Substitution Principle, isso significa deslocar a variação para fora do núcleo
e manter explícita a colaboração principal.
interface BaseActionProps {
tone?: "primary" | "ghost";
children: React.ReactNode;
}
type ButtonAction = BaseActionProps &
React.ComponentProps<"button"> & {
href?: never;
};
type LinkAction = BaseActionProps &
React.ComponentProps<"a"> & {
href: string;
disabled?: never;
type?: never;
};
export type ActionProps = ButtonAction | LinkAction;
export function Action(props: ActionProps) {
if ("href" in props) {
const { tone = "primary", children, ...rest } = props;
return (
<a className={`action action-${tone}`} {...rest}>
{children}
</a>
);
}
const { tone = "primary", children, ...rest } = props;
return (
<button className={`action action-${tone}`} {...rest}>
{children}
</button>
);
}
O ganho não é apenas organizacional. Teste fica mais barato, Storybook fica mais
isolado, documentação fica mais honesta e o review passa a enxergar claramente o que
mudou e o que permaneceu protegido.
9. Exemplo em backend e arquitetura
Princípios SOLID ficam mais úteis quando atravessam fronteiras de stack. O backend
abaixo replica a mesma ideia em termos de caso de uso, porta, contrato comportamental ou
colaboração explícita, dependendo do princípio em foco.
export interface RefundablePaymentMethod {
authorize(input: { amount: number; orderId: string }): Promise<{ authorizationId: string }>;
refund(input: { authorizationId: string; amount: number }): Promise<void>;
}
export class StripeCard implements RefundablePaymentMethod {
async authorize(input: { amount: number; orderId: string }) {
return { authorizationId: `card_${input.orderId}` };
}
async refund(input: { authorizationId: string; amount: number }) {
await stripe.refunds.create({ payment_intent: input.authorizationId, amount: input.amount });
}
}
export interface AuthorizationOnlyPaymentMethod {
authorize(input: { amount: number; orderId: string }): Promise<{ authorizationId: string }>;
}
export class PixAuthorization implements AuthorizationOnlyPaymentMethod {
async authorize(input: { amount: number; orderId: string }) {
return { authorizationId: `pix_${input.orderId}` };
}
}
Quando a arquitetura backend internaliza o mesmo princípio, o time inteiro passa a falar
a mesma língua. Isso encurta discussões entre frontend, backend, plataforma e QA, porque
o desenho deixa de depender de nomenclatura casual.
10. Estratégia de testes
Princípio sem teste vira opinião bem-intencionada. O jeito mais seguro de preservar a
fronteira correta é transformar o comportamento central em algo que a suíte consegue
proteger com foco e velocidade.
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Action } from "./Action";
function shouldBehaveLikeButton(renderAction: () => JSX.Element) {
it("respects disabled semantics", async () => {
const user = userEvent.setup();
const onClick = vi.fn();
render(renderAction());
const button = screen.getByRole("button");
await user.click(button);
expect(onClick).not.toHaveBeenCalled();
});
}
shouldBehaveLikeButton(() => (
<Action disabled onClick={vi.fn()}>
Comprar
</Action>
));
A recomendação prática é separar três níveis: teste puro para regra ou contrato, teste
de integração para a costura da camada e um número pequeno de testes end-to-end para
validar a história inteira. Quando tudo vira E2E, o princípio perde efeito porque o
feedback fica lento demais.
11. Observabilidade e métricas
Arquitetura só vira vantagem operacional quando você consegue enxergar seus efeitos. Por
isso vale registrar métricas que revelem acoplamento, custo de mudança e estabilidade de
contrato.
- Monitore quais arquivos concentram mais mudanças ligadas a Liskov Substitution
Principle.
- Registre tempo médio de review e quantidade de arquivos alterados por feature simples.
- Observe tempo de teste, número de mocks por suíte e falhas disparadas por mudanças não
relacionadas.
- Em produção, correlacione incidentes com adapters, componentes ou fluxos que
concentram variabilidade.
- Use dashboards de mudança por release para transformar smell arquitetural em dado
operacional.
| Métrica | Antes | Depois |
|---|
| Bugs de QA por props ignoradas | 15 por mês | 1 por mês |
| Erros de acessibilidade detectados por release | 7 | 0 a 1 |
| Tempo gasto explicando exceções de API | médio | baixo |
| Hotfixes por wrappers incompatíveis | 4 por trimestre | 0 a 1 por trimestre |
12. Checklist de refatoração
- Escolha um hotspot real em vez de refatorar área estável só por estética.
- Congele o comportamento com testes pequenos antes de mover fronteiras.
- Extraia primeiro o detalhe mais volátil ou o contrato mais mentiroso.
- Reduza a superfície pública antes de otimizar nomes internos.
- Adicione mappers, providers, unions ou slots apenas quando eles diminuem surpresa
real.
- Revise imports e garanta que a direção de dependência ficou mais clara depois da
mudança.
- Meça tempo de review, quantidade de mocks e arquivos tocados nas próximas sprints
para validar se o corte ajudou.
13. Trade-offs honestos
Contratos mais honestos às vezes reduzem a sensação de API “unificada”. Esse é um preço
pequeno perto do custo de compatibilidades falsas.
Unions discriminadas e contract tests adicionam verbosidade. Em troca, eliminam bugs que
TypeScript sozinho não consegue capturar quando a assinatura é permissiva demais.
Nem toda diferença de implementação exige contrato novo. O que exige contrato novo é
diferença observável para o consumidor. Esse filtro evita tanto abstração prematura
quanto mentiras elegantes.
14. Anti-patterns comuns
- Subclasse ou wrapper que aceita a mesma API mas ignora
disabled, required, type
ou outra parte central do contrato.
- Método opcional que vira exceção em runtime para uma implementação específica.
- Uso de herança para reaproveitar estilos ou helpers quando a semântica pública já
divergiu.
- Tipo base permissivo demais, obrigando cada consumidor a aprender as limitações
escondidas de cada subtipo.
- Flags internas que mudam comportamento essencial sem alterar a assinatura pública.
15. Perguntas de code review
- O subtipo introduz nova precondição que o tipo base não comunicava?
- Existe alguma prop aceita pela API mas sem efeito nesta implementação?
- O consumidor consegue usar o subtipo sem saber detalhes internos?
- As pós-condições do contrato base continuam válidas?
- Estamos unificando API por conveniência visual ou por equivalência real de
comportamento?
- A acessibilidade muda de forma relevante entre variantes?
- Há necessidade de
instanceof para descobrir se um método pode ser chamado?
- Esse wrapper preserva foco, teclado e eventos como o consumidor espera?
- A assinatura pública está escondendo dois contratos diferentes?
- Se eu trocar a implementação em runtime, o chamador continuará correto?
- Existe teste de conformidade ou estamos confiando apenas em inspeção manual?
- O subtipo está enfraquecendo garantias de erro, retry ou idempotência?
- O contrato base poderia ser menor e mais honesto?
- Há métodos que deveriam estar em interfaces separadas?
- A variação é melhor resolvida por composição do que por substituição?
- O tipo está prometendo suporte a submit ou navegação sem realmente entregar?
- O nome do componente induz o time a supor semântica que não existe?
- O contrato documenta claramente o que muda entre as variantes?
- Há warnings de runtime cobrindo combinações inválidas em desenvolvimento?
- A suíte de testes trata comportamento observável como primeira classe?
16. Plano 30-60-90 dias
30 dias
Mapeie os pontos mais frágeis relacionados a Liskov Substitution Principle. Escolha um
fluxo pequeno, mas crítico o bastante para gerar aprendizado. O objetivo do primeiro mês
não é purismo. É provar uma redução clara de custo de mudança.
- Identificar hotspots de incidentes e arquivos com maior dispersão de autoria.
- Criar métricas básicas de arquivos alterados, mocks por teste e tempo médio de review.
- Selecionar um fluxo candidato para refatoração guiada por testes.
60 dias
Com a primeira fronteira estabilizada, o foco passa a ser repetibilidade. O time precisa
transformar aprendizado em padrão local: exemplos, snippet, convenção de review e
documentação curta.
- Replicar o padrão em um segundo fluxo para validar generalização.
- Adicionar exemplos em Storybook, ADRs ou documentação de arquitetura.
- Ensinar o padrão em pairing e revisar PRs usando a mesma linguagem.
90 dias
No terceiro mês, a meta é institucionalizar o princípio como hábito operacional. Isso
inclui critérios de review, métricas de manutenção e ownership explícito dos contratos
mais sensíveis.
- Auditar contratos e componentes ainda frágeis.
- Conectar métricas de qualidade com planejamento de manutenção.
- Registrar exemplos bons e ruins para onboarding de novos engenheiros.
17. Caso composto e métricas
O cenário abaixo é composto a partir de padrões recorrentes em times de produto com
stack React, TypeScript e Node. A intenção não é vender milagre nem fingir benchmark
universal. A intenção é mostrar como princípios bem aplicados reduzem fricção
operacional de forma mensurável.
| Métrica | Antes | Depois |
|---|
| Bugs de QA por props ignoradas | 15 por mês | 1 por mês |
| Erros de acessibilidade detectados por release | 7 | 0 a 1 |
| Tempo gasto explicando exceções de API | médio | baixo |
| Hotfixes por wrappers incompatíveis | 4 por trimestre | 0 a 1 por trimestre |
O ponto importante nesses números é a direção, não o valor exato. Quando o princípio
entra no desenho certo, o time muda menos arquivos por feature, discute menos exceções
em review e lida com menos regressões ligadas a mudanças não relacionadas.
18. ADR template
Quando a decisão é importante o bastante para afetar vários fluxos, vale registrá-la em
uma ADR curta. O template abaixo ajuda a manter contexto, decisão e consequência num
formato que o time consegue revisitar sem romantizar a escolha original.
# ADR: Liskov Substitution Principle as a design constraint
## Context
- Surface under review: design system com ações polimórficas e integrações de pagamento
- Current pain: wrappers compatíveis na aparência, mas divergentes no comportamento
- Risk if unchanged: bugs silenciosos, acessibilidade quebrada e contratos mentirosos
## Decision
- Apply Liskov Substitution Principle through unions discriminadas, interfaces menores e contract tests por implementação
- Keep tokens visuais e capacidades realmente compartilhadas stable
- Route future variation through tipos explícitos para variações comportamentais
## Consequences
- Positive: API honesta e menos regressão silenciosa
- Negative: mais verbosidade em tipagem e testes
- Follow-up: auditar wrappers existentes e reclassificar contratos incompatíveis
19. FAQ
LSP só importa se eu uso herança?
Não. No ecossistema React e TypeScript, as violações mais comuns aparecem em wrappers,
componentes polimórficos e interfaces compartilhadas entre implementações diferentes. O
problema é a substituição comportamental, não a palavra-chave extends.
TypeScript não resolve isso sozinho?
Não. TypeScript valida forma estrutural. LSP exige equivalência de comportamento. Um
subtipo pode compilar e ainda assim ignorar uma prop, lançar exceção inesperada ou
exigir um estado extra em runtime.
Union discriminada substitui LSP?
Ela ajuda muito porque torna diferenças explícitas. Ainda assim, você precisa validar
comportamento observável com testes e documentação. Tipagem sozinha não garante
acessibilidade, side effects corretos ou semântica de runtime.
Pode, e muitas vezes deve. O erro é manter a mesma API quando as garantias já
divergiram. Visual compartilhado não implica contrato compartilhado.
Como identificar precondição escondida?
Procure por frases como “isso só funciona se...” que não aparecem no contrato base.
Quando o consumidor precisa aprender esse detalhe fora da assinatura, a substituição
está em risco.
LSP ajuda acessibilidade?
Muito. Componentes acessíveis dependem de promessas claras sobre foco, teclado, submit,
labels e roles. Quando wrappers quebram essas garantias, LSP costuma ser a lente mais
útil para explicar o problema.
Contract tests valem o custo?
Sim, especialmente em design systems, SDKs e integrações de pagamento, notificação e
storage. Eles capturam diferenças que code review ou tipos deixam passar.
Se uma implementação suporta menos recursos, o que fazer?
Redesenhe o contrato. Crie uma interface menor e componha capacidades adicionais por
outra interface. O que não vale é fingir suporte completo e falhar depois.
Não. Eles se complementam. OCP fala sobre pontos de extensão. LSP fala sobre honestidade
das extensões que você criou.
Qual é a frase para lembrar em review?
Mesma promessa, mesmo comportamento observável. Se isso não for verdade, não use a mesma
interface.
20. Conclusão
LSP protege o consumidor do pior tipo de bug: aquele que parece compatível até a hora em
que importa. Quando a API pública promete mais do que a implementação entrega, o sistema
continua parecendo organizado enquanto acumula exceções silenciosas.
A solução raramente é mais herança. Quase sempre é mais honestidade: contratos menores,
unions explícitas, composition e testes de conformidade. Isso reduz atrito entre design,
produto, QA e acessibilidade porque o comportamento deixa de depender de suposição.
Leve uma pergunta para o próximo review: se eu trocar esta implementação pela outra sem
avisar o chamador, ele continua correto? Se a resposta for não, o tipo talvez esteja
mentindo.
21. Referências
- Barbara Liskov — Data Abstraction and Hierarchy, 1987.
- Robert C. Martin — Agile Software Development, capítulo sobre LSP.
- TypeScript Handbook — Advanced Types and narrowing:
https://www.typescriptlang.org/docs/
- React Docs — Accessibility basics: https://react.dev/learn/accessibility
- WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
- Kent C. Dodds — Writing tests that focus on user behavior.
- Martin Fowler — Refactoring and the discipline of making contracts explicit.
Long-Form Article (English)
1. Why this principle matters in production
LSP matters every time a component, gateway, or service claims compatibility with a base
contract. If callers need extra tribal knowledge to use the substitute safely, the
contract is already broken.
This is why many “polymorphic” abstractions fail in production. They share names and
signatures, but not semantics. The result is fragile UI, hidden runtime branches, and QA
rules that live outside the type system.
2. Practical rules of thumb
- Substitutes cannot add hidden preconditions.
- Substitutes cannot silently weaken guarantees.
- Treat accessibility semantics as part of the public contract.
- Prefer discriminated unions when behaviors truly diverge.
- Back every public contract with compliance-style tests.
3. Architecture reading
The fastest way to operationalize Liskov Substitution Principle is to describe the
contract in the language of the use case and then protect that contract with focused
tests. Once you do that, refactoring stops being philosophical and starts becoming a
cost-control move.
This is where copywriting discipline helps engineering writing: clarity beats
cleverness, specificity beats vagueness, and every section should move one argument
forward. Senior engineers do not need more adjectives. They need reliable boundaries and
language they can apply on Monday morning.
4. Frontend example
A good frontend example exposes the user-facing promise and removes accidental detail
from the component boundary.
interface BaseActionProps {
tone?: "primary" | "ghost";
children: React.ReactNode;
}
type ButtonAction = BaseActionProps &
React.ComponentProps<"button"> & {
href?: never;
};
type LinkAction = BaseActionProps &
React.ComponentProps<"a"> & {
href: string;
disabled?: never;
type?: never;
};
export type ActionProps = ButtonAction | LinkAction;
export function Action(props: ActionProps) {
if ("href" in props) {
const { tone = "primary", children, ...rest } = props;
return (
<a className={`action action-${tone}`} {...rest}>
{children}
</a>
);
}
const { tone = "primary", children, ...rest } = props;
return (
<button className={`action action-${tone}`} {...rest}>
{children}
</button>
);
}
5. Backend example
Backend architecture benefits from the same principle because integrations, persistence,
policies, and orchestration often drift together unless the boundary is deliberate.
export interface RefundablePaymentMethod {
authorize(input: { amount: number; orderId: string }): Promise<{ authorizationId: string }>;
refund(input: { authorizationId: string; amount: number }): Promise<void>;
}
export class StripeCard implements RefundablePaymentMethod {
async authorize(input: { amount: number; orderId: string }) {
return { authorizationId: `card_${input.orderId}` };
}
async refund(input: { authorizationId: string; amount: number }) {
await stripe.refunds.create({ payment_intent: input.authorizationId, amount: input.amount });
}
}
export interface AuthorizationOnlyPaymentMethod {
authorize(input: { amount: number; orderId: string }): Promise<{ authorizationId: string }>;
}
export class PixAuthorization implements AuthorizationOnlyPaymentMethod {
async authorize(input: { amount: number; orderId: string }) {
return { authorizationId: `pix_${input.orderId}` };
}
}
6. Testing strategy
Use tests that speak the contract. Compliance or contract-style suites keep multiple
implementations honest, while focused domain tests keep feedback fast.
import { render, screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { Action } from "./Action";
function shouldBehaveLikeButton(renderAction: () => JSX.Element) {
it("respects disabled semantics", async () => {
const user = userEvent.setup();
const onClick = vi.fn();
render(renderAction());
const button = screen.getByRole("button");
await user.click(button);
expect(onClick).not.toHaveBeenCalled();
});
}
shouldBehaveLikeButton(() => (
<Action disabled onClick={vi.fn()}>
Comprar
</Action>
));
7. Review checklist
- O subtipo introduz nova precondição que o tipo base não comunicava?
- Existe alguma prop aceita pela API mas sem efeito nesta implementação?
- O consumidor consegue usar o subtipo sem saber detalhes internos?
- As pós-condições do contrato base continuam válidas?
- Estamos unificando API por conveniência visual ou por equivalência real de
comportamento?
- A acessibilidade muda de forma relevante entre variantes?
- Há necessidade de
instanceof para descobrir se um método pode ser chamado?
- Esse wrapper preserva foco, teclado e eventos como o consumidor espera?
- A assinatura pública está escondendo dois contratos diferentes?
- Se eu trocar a implementação em runtime, o chamador continuará correto?
8. FAQ
Why is LSP so often violated in design systems?
Because teams optimize for visual reuse and forget that semantics are part of the API. A
link styled like a button still navigates like a link.
What is the fastest guardrail?
Write contract tests around observable promises such as click handling, disabled
behavior, focus, submit, and error semantics.
Should I avoid polymorphism?
No. You should avoid dishonest polymorphism. Good polymorphism keeps the same contract.
If the contract changes, expose that change explicitly.
Does backend code suffer from the same issue?
Absolutely. Payment methods, notification channels, storage adapters, and queue clients
often diverge in capabilities. Honest contracts matter there just as much as in UI.
9. References
- Barbara Liskov — Data Abstraction and Hierarchy, 1987.
- Robert C. Martin — Agile Software Development, capítulo sobre LSP.
- TypeScript Handbook — Advanced Types and narrowing:
https://www.typescriptlang.org/docs/
- React Docs — Accessibility basics: https://react.dev/learn/accessibility
- WAI-ARIA Authoring Practices: https://www.w3.org/WAI/ARIA/apg/
- Kent C. Dodds — Writing tests that focus on user behavior.
- Martin Fowler — Refactoring and the discipline of making contracts explicit.
#newshortarticle
PT-BR
Liskov Substitution Principle em uma frase: mesma promessa, mesmo comportamento
observável.
Se você lembrar apenas de uma heurística, lembre desta: mesma promessa, mesmo
comportamento observável. Esse princípio existe para reduzir blast radius, tornar o
contrato mais honesto e permitir mudanças previsíveis sem reescrever o núcleo.
- Sinal forte de violação: Props aceitas pela interface pública não têm efeito em certas
variantes.
- Primeiro passo recomendado: Escreva o contrato em termos de efeitos observáveis. O que
o consumidor pode esperar ao passar
disabled, onSubmit, refund ou close?
- Métrica para acompanhar: Bugs de QA por props ignoradas
English
Liskov Substitution Principle in one line: mesma promessa, mesmo comportamento
observável.
Use the principle as an operational filter during code review. If the next requirement
forces the same module to absorb unrelated reasons to change, hidden preconditions, or
volatile details, the boundary needs work.
- Primary smell: Props aceitas pela interface pública não têm efeito em certas
variantes.
- First move: Escreva o contrato em termos de efeitos observáveis. O que o consumidor
pode esperar ao passar
disabled, onSubmit, refund ou close?
- Track this metric: Bugs de QA por props ignoradas
Appendix A: Catálogo de smells recorrentes
- Sinal 1: LSP está em risco quando um wrapper aceita as mesmas props mas ignora
disabled ou submit. O efeito colateral mais comum é o consumidor aprende exceções fora
do contrato.
- Sinal 2: LSP está em risco quando uma implementação de gateway lança NotImplemented
para método obrigatório. O efeito colateral mais comum é a substituição falha no pior
momento possível.
- Sinal 3: LSP está em risco quando a interface pública aceita combinação inválida por
comodidade. O efeito colateral mais comum é o runtime precisa defender o que o tipo
não explicou.
- Sinal 4: LSP está em risco quando dois componentes compartilham nome e estilo, mas não
a semântica. O efeito colateral mais comum é QA precisa documentar variações
manualmente.
- Sinal 5: LSP está em risco quando há branches escondidos para adaptar diferenças
irreconciliáveis. O efeito colateral mais comum é a API pública fica confortável e
enganosa.
Appendix B: Prompts de pairing e coaching técnico
- Prompt 1: durante o pairing, pergunte 'qual promessa observável o consumidor assume ao
ler este tipo?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 2: durante o pairing, pergunte 'qual pré-condição extra está sendo cobrada sem
aparecer na assinatura?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 3: durante o pairing, pergunte 'que teste de comportamento faria esta mentira
aparecer imediatamente?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 4: durante o pairing, pergunte 'estamos reaproveitando visual ou reaproveitando
contrato?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 5: durante o pairing, pergunte 'seria mais honesto expor duas interfaces
menores?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o teste
que protege essa decisão.
Appendix C: Movimentos de refatoração que preservam o contrato
- Movimento 1: substituir herança por composição quando a semântica divergir. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 2: usar
never e unions discriminadas para proibir combinações inválidas.
Antes de aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 3: criar suíte de contract tests por implementação. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
- Movimento 4: documentar acessibilidade e side effects como parte do contrato. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 5: separar capacidades opcionais em interfaces distintas. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
Appendix A: Catálogo de smells recorrentes
- Sinal 1: LSP está em risco quando um wrapper aceita as mesmas props mas ignora
disabled ou submit. O efeito colateral mais comum é o consumidor aprende exceções fora
do contrato.
- Sinal 2: LSP está em risco quando uma implementação de gateway lança NotImplemented
para método obrigatório. O efeito colateral mais comum é a substituição falha no pior
momento possível.
- Sinal 3: LSP está em risco quando a interface pública aceita combinação inválida por
comodidade. O efeito colateral mais comum é o runtime precisa defender o que o tipo
não explicou.
- Sinal 4: LSP está em risco quando dois componentes compartilham nome e estilo, mas não
a semântica. O efeito colateral mais comum é QA precisa documentar variações
manualmente.
- Sinal 5: LSP está em risco quando há branches escondidos para adaptar diferenças
irreconciliáveis. O efeito colateral mais comum é a API pública fica confortável e
enganosa.
Appendix B: Prompts de pairing e coaching técnico
- Prompt 1: durante o pairing, pergunte 'qual promessa observável o consumidor assume ao
ler este tipo?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 2: durante o pairing, pergunte 'qual pré-condição extra está sendo cobrada sem
aparecer na assinatura?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 3: durante o pairing, pergunte 'que teste de comportamento faria esta mentira
aparecer imediatamente?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 4: durante o pairing, pergunte 'estamos reaproveitando visual ou reaproveitando
contrato?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 5: durante o pairing, pergunte 'seria mais honesto expor duas interfaces
menores?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o teste
que protege essa decisão.
Appendix C: Movimentos de refatoração que preservam o contrato
- Movimento 1: substituir herança por composição quando a semântica divergir. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 2: usar
never e unions discriminadas para proibir combinações inválidas.
Antes de aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 3: criar suíte de contract tests por implementação. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
- Movimento 4: documentar acessibilidade e side effects como parte do contrato. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 5: separar capacidades opcionais em interfaces distintas. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
Appendix A: Catálogo de smells recorrentes
- Sinal 1: LSP está em risco quando um wrapper aceita as mesmas props mas ignora
disabled ou submit. O efeito colateral mais comum é o consumidor aprende exceções fora
do contrato.
- Sinal 2: LSP está em risco quando uma implementação de gateway lança NotImplemented
para método obrigatório. O efeito colateral mais comum é a substituição falha no pior
momento possível.
- Sinal 3: LSP está em risco quando a interface pública aceita combinação inválida por
comodidade. O efeito colateral mais comum é o runtime precisa defender o que o tipo
não explicou.
- Sinal 4: LSP está em risco quando dois componentes compartilham nome e estilo, mas não
a semântica. O efeito colateral mais comum é QA precisa documentar variações
manualmente.
- Sinal 5: LSP está em risco quando há branches escondidos para adaptar diferenças
irreconciliáveis. O efeito colateral mais comum é a API pública fica confortável e
enganosa.
Appendix B: Prompts de pairing e coaching técnico
- Prompt 1: durante o pairing, pergunte 'qual promessa observável o consumidor assume ao
ler este tipo?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 2: durante o pairing, pergunte 'qual pré-condição extra está sendo cobrada sem
aparecer na assinatura?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 3: durante o pairing, pergunte 'que teste de comportamento faria esta mentira
aparecer imediatamente?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 4: durante o pairing, pergunte 'estamos reaproveitando visual ou reaproveitando
contrato?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 5: durante o pairing, pergunte 'seria mais honesto expor duas interfaces
menores?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o teste
que protege essa decisão.
Appendix C: Movimentos de refatoração que preservam o contrato
- Movimento 1: substituir herança por composição quando a semântica divergir. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 2: usar
never e unions discriminadas para proibir combinações inválidas.
Antes de aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 3: criar suíte de contract tests por implementação. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
- Movimento 4: documentar acessibilidade e side effects como parte do contrato. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 5: separar capacidades opcionais em interfaces distintas. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
Appendix A: Catálogo de smells recorrentes
- Sinal 1: LSP está em risco quando um wrapper aceita as mesmas props mas ignora
disabled ou submit. O efeito colateral mais comum é o consumidor aprende exceções fora
do contrato.
- Sinal 2: LSP está em risco quando uma implementação de gateway lança NotImplemented
para método obrigatório. O efeito colateral mais comum é a substituição falha no pior
momento possível.
- Sinal 3: LSP está em risco quando a interface pública aceita combinação inválida por
comodidade. O efeito colateral mais comum é o runtime precisa defender o que o tipo
não explicou.
- Sinal 4: LSP está em risco quando dois componentes compartilham nome e estilo, mas não
a semântica. O efeito colateral mais comum é QA precisa documentar variações
manualmente.
- Sinal 5: LSP está em risco quando há branches escondidos para adaptar diferenças
irreconciliáveis. O efeito colateral mais comum é a API pública fica confortável e
enganosa.
Appendix B: Prompts de pairing e coaching técnico
- Prompt 1: durante o pairing, pergunte 'qual promessa observável o consumidor assume ao
ler este tipo?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 2: durante o pairing, pergunte 'qual pré-condição extra está sendo cobrada sem
aparecer na assinatura?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 3: durante o pairing, pergunte 'que teste de comportamento faria esta mentira
aparecer imediatamente?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 4: durante o pairing, pergunte 'estamos reaproveitando visual ou reaproveitando
contrato?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 5: durante o pairing, pergunte 'seria mais honesto expor duas interfaces
menores?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o teste
que protege essa decisão.
Appendix C: Movimentos de refatoração que preservam o contrato
- Movimento 1: substituir herança por composição quando a semântica divergir. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 2: usar
never e unions discriminadas para proibir combinações inválidas.
Antes de aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 3: criar suíte de contract tests por implementação. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
- Movimento 4: documentar acessibilidade e side effects como parte do contrato. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 5: separar capacidades opcionais em interfaces distintas. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
Appendix A: Catálogo de smells recorrentes
- Sinal 1: LSP está em risco quando um wrapper aceita as mesmas props mas ignora
disabled ou submit. O efeito colateral mais comum é o consumidor aprende exceções fora
do contrato.
- Sinal 2: LSP está em risco quando uma implementação de gateway lança NotImplemented
para método obrigatório. O efeito colateral mais comum é a substituição falha no pior
momento possível.
- Sinal 3: LSP está em risco quando a interface pública aceita combinação inválida por
comodidade. O efeito colateral mais comum é o runtime precisa defender o que o tipo
não explicou.
- Sinal 4: LSP está em risco quando dois componentes compartilham nome e estilo, mas não
a semântica. O efeito colateral mais comum é QA precisa documentar variações
manualmente.
- Sinal 5: LSP está em risco quando há branches escondidos para adaptar diferenças
irreconciliáveis. O efeito colateral mais comum é a API pública fica confortável e
enganosa.
Appendix B: Prompts de pairing e coaching técnico
- Prompt 1: durante o pairing, pergunte 'qual promessa observável o consumidor assume ao
ler este tipo?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 2: durante o pairing, pergunte 'qual pré-condição extra está sendo cobrada sem
aparecer na assinatura?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 3: durante o pairing, pergunte 'que teste de comportamento faria esta mentira
aparecer imediatamente?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 4: durante o pairing, pergunte 'estamos reaproveitando visual ou reaproveitando
contrato?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 5: durante o pairing, pergunte 'seria mais honesto expor duas interfaces
menores?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o teste
que protege essa decisão.
Appendix C: Movimentos de refatoração que preservam o contrato
- Movimento 1: substituir herança por composição quando a semântica divergir. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 2: usar
never e unions discriminadas para proibir combinações inválidas.
Antes de aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 3: criar suíte de contract tests por implementação. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
- Movimento 4: documentar acessibilidade e side effects como parte do contrato. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 5: separar capacidades opcionais em interfaces distintas. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
Appendix A: Catálogo de smells recorrentes
- Sinal 1: LSP está em risco quando um wrapper aceita as mesmas props mas ignora
disabled ou submit. O efeito colateral mais comum é o consumidor aprende exceções fora
do contrato.
- Sinal 2: LSP está em risco quando uma implementação de gateway lança NotImplemented
para método obrigatório. O efeito colateral mais comum é a substituição falha no pior
momento possível.
- Sinal 3: LSP está em risco quando a interface pública aceita combinação inválida por
comodidade. O efeito colateral mais comum é o runtime precisa defender o que o tipo
não explicou.
- Sinal 4: LSP está em risco quando dois componentes compartilham nome e estilo, mas não
a semântica. O efeito colateral mais comum é QA precisa documentar variações
manualmente.
- Sinal 5: LSP está em risco quando há branches escondidos para adaptar diferenças
irreconciliáveis. O efeito colateral mais comum é a API pública fica confortável e
enganosa.
Appendix B: Prompts de pairing e coaching técnico
- Prompt 1: durante o pairing, pergunte 'qual promessa observável o consumidor assume ao
ler este tipo?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 2: durante o pairing, pergunte 'qual pré-condição extra está sendo cobrada sem
aparecer na assinatura?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 3: durante o pairing, pergunte 'que teste de comportamento faria esta mentira
aparecer imediatamente?' e só aceite a resposta quando ela explicar o contrato, a
fronteira e o teste que protege essa decisão.
- Prompt 4: durante o pairing, pergunte 'estamos reaproveitando visual ou reaproveitando
contrato?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o
teste que protege essa decisão.
- Prompt 5: durante o pairing, pergunte 'seria mais honesto expor duas interfaces
menores?' e só aceite a resposta quando ela explicar o contrato, a fronteira e o teste
que protege essa decisão.
Appendix C: Movimentos de refatoração que preservam o contrato
- Movimento 1: substituir herança por composição quando a semântica divergir. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 2: usar
never e unions discriminadas para proibir combinações inválidas.
Antes de aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 3: criar suíte de contract tests por implementação. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.
- Movimento 4: documentar acessibilidade e side effects como parte do contrato. Antes de
aplicar, registre o motivo da mudança, o arquivo com maior volatilidade e o
comportamento que não pode regredir.
- Movimento 5: separar capacidades opcionais em interfaces distintas. Antes de aplicar,
registre o motivo da mudança, o arquivo com maior volatilidade e o comportamento que
não pode regredir.