Download to read offline
Uploaded byLaurence Chen
On component interface
The document discusses component interface design. It defines an interface and contrasts an API approach with a protocol approach. It provides examples of common bad interface practices like deceptive APIs and DSLs as APIs. It also discusses issues with distributed systems like idempotency keys and the coupling spectrum. The document emphasizes designing error messages for the caller and distinguishing component purpose from implementation.
On component interface
- 1. On component interface LaurenceChen twitter: humorless https://replware.dev/
- 2. What % oftime do you spend on interface
- 3. Agenda ● About theinterface ● About the component ● Component interface design ○ Common bad practices ○ Distributed system issues ● Error messages
- 4. What is aninterface?
- 5. Case study: vimvs Emacs ● Vim has an editing interface with several modes, a modal interface ● Emacs provides Elisp programming interface
- 6. Vim normal modesemantics ● {Operator}{Count}{Motion} ● {Operator}{Motion} ● Example: ○ d2w // delete 2 words ○ d/hello // delete everything until first occurance of hello
- 7. interface simple vs implementationsimple impl simple interface simple 100 bad 90 + E(t) 90 - E(t)
- 8. About the component ●Why we separate our code into components? ○ think at higher level ○ divide a codebase among different developers ● How to identify the component within an application? ○ begin from purpose
- 9. How to findout the purpose? purpose/strategy implementation/tactics ask why? ask how?
- 10. Case Study: purposevs implementation ● CAR, CDR ○ Naming for implementation ○ CAR - Copy Address Register ○ CDR - Copy Decrement Register ● first, rest ○ Naming for purpose
- 11. Guidelines of groupingcode into components ● The functions work on the same kind of data ● The data has a common scope of lifetime ● The likelihood of change from external requirement is similar ● The resources needed are similar
- 12.
- 13. Component interface design Thereare two basic approaches to design the interface of a component ● API ○ This approach usually contains an implicit protocol. ● Protocol
- 14. Common bad practices ●Deceptive API ● DSL as API ● The problems with RESTful APIs ● RPC is a bad idea
- 15. Deceptive API example Database.connect(...); OfflineQueue.start(...); CreditCardProcessor.init(...); CreditCardcc = new CreditCard("12.34"); cc.charge(100);
- 16. Better design -Remove hidden global states db = new Database(); queue = new OfflineQueue(db); ccProc = new CCProcessor(queue); CreditCard cc; cc = new CreditCar("12.34", ccProc); cc.charge(100);
- 17. DSL as API ●Example: SQL, build tools ● As time goes by, the complexity of the DSL increases. ● DSL is a good thing when it is used with constraints. ○ Turing complete functionalities should go into API part.
- 18. Bad design -SQL/ build tool
- 19. Good design -Datomic
- 20. Problematic RESTful API ●Web resource depends directly on database entity. ● GET/POST/PUT/DELETE ● How long individual resource URLs are good for and whether you have to remember them over time? ● N + 1 problem
- 21. Better design: CQRShttp API ● Use Query/Command only ○ Query for read or return data ○ Command for write or making changes
- 22. RPC is abad idea ● Request-response is a network-level message exchange pattern, whereas RPC is an application-level abstraction intended. ● Equating RPC with synchronous messaging will cause: ○ No reasonable abstraction for network failure. ○ Easily design a system with too long response time.
- 23. Distributed system issues ●Idempotency key ● Coupling spectrum
- 24. Idempotency Key ● Anidempotency key is a unique value generated by the client which the server uses to recognize subsequent retries of the same request.
- 25. If you donot handle idempotence issues, well... ● 都是 They 的錯！
- 26. Coupling Spectrum Tight coupling Loose coupling ObjectAPI RPC = remote procedure call Web API Queue Log ???
- 27. Why introducing aqueue? ● add more indirection into the system. ● modeling the backpressure ● making the system easier to understand, manage, monitor ● making better use of computational resources.
- 28. A quick noteabout Kafka ● It can be used as hipster queue. ● However, it was originally designed to be a log abstraction.
- 29.
- 30.
- 31. What do weactually decouple ● Log: decoupling of the single domain logic. ● Queue: decoupling of the single processing speed. ● Web API: decoupling of the single processing entity and programming language.
- 32. Error message design ●Don’t make assumptions about how the caller will use your component. ● Can your error message really tell the user what to do next?
- 33. Bad design: Doingtoo much
- 34. Delegate the rightsto the caller
- 35.
- 36. Is this goodenough?
- 37.
- 38. Conclusions - Interfacedesign is not easy ● We need to distinguish between purpose & implementation. ● We need to avoid some bad practices. ● We need to think about the surrounding distributed system. ● We need to design proper error messages.
- 39. Reference ● Hexagonal architecture. https://herbertograca.com/2017/11/16/explicit-ar chitecture-01-ddd-hexagonal-onion-clean-cqrs-ho w-i-put-it-all-together/comment-page-1/ ●OO design for testability - Miško Hevery ● Narcissistic Design - Stuart Halloway ● A quick comparison between Kafka and Message Queues https://hackernoon.com/a-super-quick-compariso n-between-kafka-and-message-queues-e69742d8 55a8
- 40. Reference ● Editinglike magic with vim operator https://www.barbarianmeetscoding.com/boost-y our-coding-fu-with-vscode-and-vim/editing-like-m agic-with-vim-operators/ ● Making reliable distributed systems in the presence of software errors. - Joe Armstrong ● Idempotency Key：原理與實測 https://william-yeh.net/post/2020/03/idempoten cy-key-test/ ● Simplifying ETL with Clojure and Datomic - Stuart Halloway