Axum Service Layer

Relevant source files

The following files were used as context for generating this wiki page:

• examples/axum_example/api/src/lib.rs
• examples/axum_example/service/Cargo.toml
• examples/axum_example/service/tests/crud_tests.rs
• examples/axum_example/api/src/graphql/query_root.rs
• examples/axum_example/entity/src/post.rs
• examples/axum_example/README.md

The Axum Service Layer serves as the core business logic and data access abstraction for the Axum-based example application. It sits between the API routing layer and the database, utilizing SeaORM to perform structured database operations. Its primary purpose is to decouple HTTP request handling from the underlying database models and persistence logic, providing a clean interface for both RESTful and GraphQL endpoints.

This layer is organized into two primary logic groups: Query for data retrieval operations and Mutation for data modification. It abstracts the complexities of pagination, entity filtering, and CRUD operations, making the service logic testable and reusable across different transport protocols like Axum's HTTP routes and Seaography's GraphQL schema.

Sources: examples/axum_example/api/src/lib.rs, examples/axum_example/service/tests/crud_tests.rs

Architecture and Components

The service layer is built on top of SeaORM and interacts with generated entities. It is consumed by the API layer, which manages state and routing.

Data Flow Architecture

The following diagram illustrates how the Axum Service Layer handles requests from the API handlers and interacts with the database.

The flow shows handlers extracting database connections from AppState and passing them to the Service Layer's Query and Mutation modules.
Sources: examples/axum_example/api/src/lib.rs:17-48, examples/axum_example/service/tests/crud_tests.rs:5-10

Core Service Components

Component	Responsibility	Relevant Files
Mutation	Handles data changes (Create, Update, Delete).	mutation.rs, crud_tests.rs
Query	Handles data retrieval and pagination.	query.rs, lib.rs
AppState	Holds the database connection and templates for Axum handlers.	api/src/lib.rs
Entities	Defines the database schema and model structures.	entity/src/post.rs

Sources: examples/axum_example/api/src/lib.rs:88-91, examples/axum_example/entity/src/post.rs

Data Access and CRUD Logic

The service layer implements standardized CRUD operations using SeaORM's active models and query builders.

Post Operations Sequence

This sequence diagram depicts the process of creating a new post through the service layer.

The handler extracts the form data into a post::Model and passes it to the mutation service, which interacts with the database via SeaORM.
Sources: examples/axum_example/api/src/lib.rs:152-167, examples/axum_example/service/tests/crud_tests.rs:13-33

Query and Pagination

The service layer provides specialized methods for paginated data retrieval.

• find_posts_in_page: Accepts a page number and posts-per-page count, returning a tuple containing the list of posts and the total number of pages.
• find_post_by_id: Retrieves a single entity by its primary key.

Sources: examples/axum_example/api/src/lib.rs:105-115, examples/axum_example/service/tests/crud_tests.rs:51-56

Integration with GraphQL and Config

The service layer also supports the dynamic GraphQL schema generation through Seaography and provides access to admin panel configurations.

GraphQL Schema Construction

The GraphQL schema is dynamically built by registering entity modules from the service layer.

The schema function in the API layer takes a DatabaseConnection and uses the Builder to register entity modules, such as post, to create a dynamic GraphQL endpoint.
Sources: examples/axum_example/api/src/graphql/query_root.rs:13-31

Admin Configuration

The service layer exposes the admin panel configuration via a dedicated endpoint.

• Endpoint: GET /api/admin/config
• Logic: Uses sea_orm_pro::ConfigParser to load TOML configurations from the pro_admin directory.

Sources: examples/axum_example/api/src/lib.rs:207-212

Testing the Service Layer

The service layer includes integrated CRUD tests that utilize an in-memory SQLite database to verify logic without requiring a persistent database environment.

Test Workflow

1. Connect to sqlite::memory:.
2. Generate the table schema from the post::Entity.
3. Execute Mutation and Query methods sequentially.
4. Assert that ActiveModel transitions and rows_affected match expected results.

Sources: examples/axum_example/service/tests/crud_tests.rs:7-80

Conclusion

The Axum Service Layer provides a structured approach to managing data operations within the sea-orm-pro ecosystem. By encapsulating logic within Query and Mutation modules, it ensures that the API layer remains focused on request handling while the service layer manages entity lifecycles and database interactions.