Objetivo
Entendo que o objetivo da pergunta seria como projetar uma API de modo a facilitar extensão e manutenção.
Princípios e ressalvas
Uma boa abordagem seria adotar princípios SOLID. Porém já foi ponderado na resposta do @Douglas, tais princípios devem ser aplicados quando fazem sentido, evitando over-engineering e otimização precoce.
Por exemplo, num projeto de curto prazo com um ou dois desenvolvedores é fácil passar por cima disso.
Por outro lado, se há perspectiva de investimento a médio ou longo prazo, se há outras pessoas do projeto ou até de outros projetos que vão consumir sua API sem saber de todos os detalhes de como ela funciona, então faz todo sentido e torna-se até necessário investir um tempo a mais para projetar algo robusto.
Fred Brooks, no The Mythical Man-Month, estima que desenvolver software para reuso requer três vezes mais esforço.
Construindo uma API robusta
Vamos a um exemplo que fica no meio entre acadêmico e "de mercado":
Construa uma API que suporte por padrão pagamentos via boleto e cartão e também permita novos meios de pagamento sem modificar as classes existentes.
Essa API é integrada com uma loja online, que possui o seguinte fluxo:
- Ao fechar a compra, o Usuário seleciona o tipo de pagamento
- O Sistema tenta efetuar o pagamento e verifica o resultado
- Se bem sucedido, o sistema registra o pagamento como efetuado
- Se for necessário aguardar confirmação (como no caso de boleto), o sistema agenda uma outra tentativa de efetuar o pagamento para o outro dia.
- Se for mal sucedido, o sistema envia uma mensagem para o usuário
Interfaces e classes básicas
public enum Status {
ERRO, SUCESSO, AGUARDANDO_CONFIRMACAO
}
public class Resultado {
Status status;
String motivo;
}
public interface MetodoPagamento {
Resultado efetuar(Compra compra);
}
Pagamento
, a classe principal
O sistema da loja então poderia implementar um serviço de pagamentos assim:
@Named
public class PagamentoService {
@Inject
PagamentoDao pagamentoDao;
@Inject
AgendamentoService agendamentoService;
@Inject
ErroPagamentoService erroPagamentoService;
// código que pode ser mais ou menos complexo dependendo
// de quantas integrações forem necessárias
Status efetuar(String usuario, MetodoPagamento metodo, Compra compra) {
Resultado r = metodo.efetuar(compra);
if (Status.ERRO == r.status) {
log.error("Erro...");
erroPagamentoService.notificarErroPagamento(usuario, compra, r.motivo);
} else if (Status.AGUARDANDO_CONFIRMACAO == r.status) {
log.info("Tenta novamente amanhã...");
agendamentoService.agendarVerificacaoPagamento(
usuario, metodo, compra);
} else {
log.info("Sucesso...");
pagamentoDao.inserir(usuario, compra);
}
return r;
}
}
Pagando com boletos
public class PagamentoBoleto implements MetodoPagamento {
public Resultado efetuar(Compra compra) {
int codigoDeBarras = CodigoDeBarras.gerar(compra);
boolean pagamentoDetectado = apiBanco.codigoDeBarrasFoiPago(codigoDeBarras);
if (pagamentoDetectado) {
return new Resultado(Status.SUCESSO, "");
}
return new Resultado(Status.AGUARDANDO_CONFIRMACAO, "Pagamento não detectado junto ao banco");
}
}
Pagando com cartão
public class PagamentoCartao implements MetodoPagamento {
private DadosCartao cartao;
public PagamentoCartao(DadosCartao cartao) {
this.cartao = cartao;
}
public Resultado efetuar(Compra compra) {
int numeroTransacao = CartaoCredito.gerarNumeroTransacao(compra);
boolean conseguiuPagar = apiBanco.pagarComCartao(cartao, compra);
if (conseguiuPagar) {
return new Resultado(Status.SUCESSO, "Transação " + numeroTransacao + " efetuada com sucesso");
}
return new Resultado(Status.ERRO, "Banco rejeitou cartão " + cartao);
}
}
Controlando tudo isso
Em algum lugar do código (no caso de um sistema web, possivelmente um controlador ou endpoint), vai haver uma código que lista os tipos de pagamento e instancia o respetivo método de pagamento.
Exemplo:
@POST("/pagar")
@Named
class PagamentoResource {
@Inject PagamentoService pagamentoService;
@POST("cartao")
public Response pagarComCartao(FormPagamentoCartao form) {
DadosCartao cartao = createDadosCartao(form);
MetodoPagamento metodo = new PagamentoCartao(cartao);
Copra compra = recuperarCompraDaSessao();
return pagar(metodo, compra);
}
@POST("boleto")
public Response pagarComBoleto(FormPagamentoBoleto form) {
DadosCartao cartao = createDadosCartao(form);
MetodoPagamento metodo = new PagamentoCartao(cartao);
Copra compra = recuperarCompraDaSessao();
return pagar(metodo, compra);
}
private Response pagar(MetodoPagamento metodo, Compra compra) {
Copra compra = recuperarCompraDaSessao();
String usuario = recuperarUsuarioLogado();
Resultado r = pagamentoService.efetuar(usuario, metodo, compra);
if (Status.SUCESSO == r.status) {
return Response.ok();
}
return createErrorResponse(r.motivo);
}
}
Obviamente, a interface do usuário também deverá refletir as opções disponíveis. Por exemplo, no caso do cartão, um formulário com os detalhes do cartão é exibido e no caso do boleto apenas uma imagem ou PDF, mas ambos não fazem parte do pagamento em si, portanto não incluídas nos exemplos.
Auto-discover or do not auto-discover, eis a questão
Existe algo que confunde um pouco os desenvolvedores quando se fala em princípios SOLID, tal como o de não alterar as classes existentes quando se adiciona um novo código, levando aqueles que conhecem um pouco mais da linguagem a logo pensar em usar reflexão para descobrir classes em tempo de execução.
Embora algumas bibliotecas ou frameworks cheguem a este nível, a interpretação mais comum não é que nenhuma classe existente deva ser modificada, mas sim uma quantidade mínima de classes, preferencialmente um único ponto do sistema que controla a funcionalidade em questão.
Um bom teste para saber se o desenvolvedor está aplicando devidamente padrões e princípios corretamente numa base de código é contar quantos pontos do sistema são afetados por uma mudança pontual. Quanto menos, melhor.
Agora, você já trabalhou em um sistema no qual, para adicionar algo mesmo que trivial você precisa mexer em múltiplas classes de todas as camadas da aplicação? E ainda por cima você nunca tem a garantia que não esqueceu de algum ponto? Isto é comum quando, ao invés de abstrair conceitos em interfaces e classes bem projetadas, sem perceber o programador repete a mesma lógica ou diferentes aspectos da mesma lógica em diferentes pontos do sistema (ainda que o código seja diferente, o que é pior ainda).
Adicionando um novo método de pagamento
Sem tocar no código, vou apenas listar o que seria necessário modificar para adicionar um pagamento, por exemplo, via PayPal:
- Outra implementação
PagamentoPaypal
.
- Novo endpoint (novo método na classe resource)
- UI relativa ao método de pagamento
Automatizando ao extremo
Suponha que estamos desenvolvendo um ERP plugável e queremos permitir novos métodos de pagamento sem modificar o núcleo.
Aí então podería-se pensar em usar reflexão para listar as classes no classpath, OSGi ou alguma outra tecnologia.
Na parte do ERP, teríamos que modificar:
- Criar uma classe para localizar plugins. O plugin deve seguir um formato estabelecido e fornecer as partes necessárias para a interface, validação e efetuação do pagamento.
- UI deve fazer o lookup por todos os métodos de pagamento e listá-los.
- UI deve conseguir inserir formulários de pagamento fornecidos pelos plugins.
- O ERP deve permitir ao plugin adicionar um novo endpoint que faça validação e chame o pagamento. Existem muitas formas de se fazer isso, mas para este exemplo suponha que o plugin pode fornecer uma nova classe resource com um endpoint qualquer.
Ainda neste caso, um desenvolvedor querendo plugar um novo método deveria:
- Implementar novo
MetodoPagamentoPaypal
- Implementar endpoint numa nova classe resource
- Fornecer UI com formulário respectivo ao tipo de pagamento
Conclusões
- "Fechado para modificação" não significa que nenhum classe do sistema precisa ser modificada, mas o mínimo possível ou razoável.
- Ambas as formas propostas para adicionar um novo pagamento requerem exatamente três adições ou modificações: método de pagamento, endpoint, UI.
- A proposta "plugável", embora não modifique as classes existentes para adicionar novos métodos de pagamento, adiciona complexidade e requer praticamente o mesmo esforço de implementação.
- Portanto, ela não é superior em si mesma, mas a escolha de uma ou outra depende de quem consome a API, ou seja, se é alguém de dentro ou fora do projeto.