How to Properly Layer Your Project: Best Practices and Alibaba Guidelines

1. Background

Many developers treat application layering as a simple three‑tier structure (controller, service, mapper) without clearly separating responsibilities, leading to tangled code, poor reuse, and maintenance headaches.

Different personal habits—some putting business logic in controllers, others in services—create inconsistent code styles that hinder team collaboration.

Facilitate future maintenance and extension.

Ensure the layering approach is accepted by the whole team.

Maintain clear boundaries for each layer's responsibilities.

2. How to Layer

2.1 Alibaba Specification

Alibaba's coding guidelines define the following layers:

Open Interface Layer : Exposes service methods as RPC or HTTP interfaces, handling gateway security and traffic control.

Terminal Display Layer : Renders templates for various clients (Velocity, JS, JSP, mobile, etc.).

Web Layer : Performs request routing, basic parameter validation, and simple non‑reusable business processing.

Service Layer : Contains concrete business logic.

Manager Layer : Provides generic services such as third‑party integration, caching, middleware handling, and aggregates multiple DAOs.

DAO Layer : Directly accesses databases like MySQL, Oracle, HBase.

2.2 Optimized Layering

Based on our experience, we propose a refined model that adds an RPC layer (similar to a controller) when using Thrift.

1. Controller/TService : Light business logic, parameter validation, and exception handling; should remain thin to allow easy replacement of the entry point.

2. Service : Handles business logic; each controller method should correspond to a service method to avoid duplicating orchestration code across different entry points.

3. Manager : Reusable logic such as caching, messaging, or composite operations that may involve multiple managers; HTTP or RPC managers perform necessary data transformations.

4. DAO : Database access layer; only services should directly invoke DAOs, and DAOs must not be accessed from controllers.

3. Domain Model Conversion Across Layers

Alibaba's guidelines define several domain models:

DO (Data Object): Directly maps to database tables, transferred via the DAO layer.

DTO (Data Transfer Object): Used by Service or Manager to transfer data outward.

BO (Business Object): Encapsulates business logic output from the Service layer.

AO (Application Object): Reusable object between Web and Service layers, closely tied to presentation.

VO (View Object): Object passed to the view/template engine.

Query: Encapsulates query parameters; avoid using generic Maps for more than two parameters.

Layer

Domain Model

Controller/TService

VO/DTO

Service/Manager

AO/BO

DAO

DO

Strictly separating models can lead to excessive conversions (3‑4 times per request), which reduces efficiency.

We recommend a balanced approach:

Allow Service/Manager layers to work directly with domain models for business assembly.

Prohibit Controllers/TService from passing domain objects to the DAO layer.

Similarly, DAO data should not be sent directly to Controllers/TService.

4. Summary

Proper layering is crucial for code reuse, clear responsibilities, and maintainable systems. While exact conventions may vary across teams, adhering to clear boundaries and ensuring each layer handles its designated concerns leads to a healthier codebase.