Common Design Issues and Best Practices for Distributed System Interfaces

As distributed architectures become increasingly common, especially with HTTP‑based interfaces serving both mobile and PC clients, many recurring design problems emerge that can affect a system's usability, scalability, and maintainability.

1. Date format – Applications exchange timestamps in either human‑readable forms (e.g., 2017-03-01 20:30:30 ) or epoch‑based long values. Human‑readable formats aid debugging but require parsing, while epoch values are more efficient. The article recommends a unified epoch‑second representation (or microseconds when needed) to avoid inconsistencies across services.

2. Decimal transmission – Floating‑point arithmetic can lose precision, as shown by the Java example where double a = 1; and double b = 0.99; produce 0.010000000000000009 . Using BigDecimal with the original string values restores accuracy. The recommended practice is to transmit decimal numbers as strings and construct high‑precision objects from those strings on the receiving side.

double a = 1; double b = 0.99; System.out.println(a - b); // 0.010000000000000009

BigDecimal abd = new BigDecimal("1"); BigDecimal bbd = new BigDecimal("0.99"); System.out.println(abd.subtract(bbd)); // 0.01

3. Result value format – Inconsistent response structures cause extra parsing work for clients. A standard JSON envelope is suggested: { "status": 200, "errorCode": 0, "message": "OK", "data": { /* business payload */ } } Separating status (business‑independent) from errorCode (business‑specific) improves clarity and reusability.

4. Idempotency – Repeating a request should not produce different side effects. The article explains why idempotency matters for retries and outlines three approaches: using naturally idempotent operations (e.g., reads), checking a business‑level key (e.g., order number), or introducing a client‑generated unique identifier such as requestId to detect duplicates.

5. Interface security – To verify caller identity and protect parameters, three schemes are compared: simple appCode , symmetric signing with a shared secret, and asymmetric signing with public‑private key pairs. For non‑performance‑critical scenarios, asymmetric signing is recommended for its stronger security and better suitability in multi‑party interactions.

6. Data dictionary – Distributed teams often suffer from inconsistent naming (e.g., Product meaning different concepts, or varied terms for points such as Point , Score , integral ). Maintaining a shared data dictionary (wiki, documentation, or version‑controlled files) helps avoid costly conversion code and reduces errors.

These guidelines, drawn from the author’s practical experience, aim to help engineers design more robust, maintainable distributed systems.