Looking for the perfect Rust microservice template
A simple starting point for a Rust microservice, prepared to scale together with your project.
Although Rust keeps gaining popularity and has lately topped the Stack Overflow developer survey, many still think of it mainly as a systems language. I’m personally a fan of Rust’s style and brevity, and I’m convinced it has a lot to offer outside classic systems programming – especially in web development, where RESTful web services make up a large part of what we do every day. One of the reasons many software houses and corporate IT departments don’t reach for Rust by default is how steep its learning curve is. At first, Rust can seem daunting, particularly to developers who haven’t encountered its distinctive approach before. Still, I don’t see why it couldn’t be put to good use wherever programming has to be efficient and reliable.
With this post, I want to question that view and nudge you to leave your comfort zone and give Rust a go on your servers and Kubernetes clusters, or wherever your everyday programming work leads you. I’ll confess to a bias: my own background, like that of many colleagues I know, has revolved around writing business logic inside microservices running as multiple instances on Kubernetes clusters (though they weren’t always Kubernetes).
In my view, sharing simple templates that work out of the box can help the Rust community grow faster. And, just like with every programming language, the support of the community is among its greatest strengths – arguably even greater than technical qualities such as memory management and speed.
Like plenty of programmers picking up Rust now, I’m a newcomer to writing production-ready web services in it, even though I have lots of experience building microservices in general. For this template, I picked libraries that, in my opinion, strike a good balance between functionality and simplicity; I realise, however, that not everyone will like my choices. Treat it as a starting point – I may improve the template over time or build variants with other libraries as requirements change. Feedback, ideas, pull requests, or even completely new templates are always appreciated.
A Subjective List of the Properties We Want from Our Microservice Template
I haven’t done any formal research, but it’s reasonable to assume that most of the microservices built today run on Kubernetes clusters, frequently hosted by well-known cloud providers such as Google, Amazon, or Azure. Still, the template we’re creating should fit various environments, and the one hard requirement is that it can be containerized with Docker without hassle.
Dockerizing the microservice is only one example, but as you’ll see, the key properties I chose for this template – listed below – are rather subjective.
- Ease of Building: Building the microservice should be simple, preferably with a mature build tool that enables fast testing and releasing, and smooth CI/CD integration. In my opinion,
cargomeets this need well, even though big codebases can result in longer build times. Luckily, this can be mitigated in several ways, which I might describe in a future article. - Configurable Web Framework: The framework that serves HTTP should be easy to configure. Most Rust web frameworks on the market today probably satisfy this.
- Library Integration: Integrating other libraries with the web framework should be easy, especially those responsible for persistence.
- Persistence with Migration Support: The persistence library we pick should make database schema migrations simple, including the ability to roll them back.
- Logging and Tracing: The service should offer easy-to-use, dependable logging and tracing.
- Scalability: The framework should cope well with changing loads, meeting the scalability requirements of our application.
- Documentation and Community Support: Thorough, easily accessible documentation, examples, and a lively community to turn to for help are a must.
This is how we ended up choosing Axum as our framework!
Why Axum?
To put it briefly: it’s modern and efficient. Some people may favour frameworks such as Actix or Rocket, or see promise in the many web frameworks that pop up in the Rust community every year (a good sign of growth!), but for me Axum checks every box – at least for the time being.
- Asynchronous by Design:
Axum is built on top of Tokio, a popular asynchronous runtime for Rust. As a result, Axum is non-blocking by nature and tuned for high throughput and low latency, which makes it a great fit for I/O-heavy applications. - Type-Safe Error Handling:
Axum makes use of Rust’s strong type system to catch mistakes at compile time, which cuts down on runtime problems and makes it more dependable in production. - Middleware Support with Tower:
Axum supports middleware through Tower, a powerful library for building robust network services. This makes it easier to add cross-cutting concerns such as logging, authentication, and metrics. - Strong Community and Ecosystem:
Since it is built on Tokio, Axum profits from a vibrant ecosystem and integrates smoothly with other libraries from the Tokio ecosystem, with community support and ongoing improvements behind it.
Naturally, Axum isn’t without flaws. It’s fairly young, less opinionated (which is exactly why we’re putting this template together), and its API isn’t yet as stable as that of some older frameworks. For the needs of this blog post and our template, though, these drawbacks can be handled. If you’ve run into specific problems with Axum in production, especially blocking ones, I’d be glad to hear about them.
Choosing a Persistence Library
A key decision is which persistence library to use for database integration. Out of the several options available in the Rust ecosystem, I went for sqlx, mainly because it’s simple and comes with a CLI that makes managing the database more convenient.
Setting up the foundation
The easiest way to begin with this template is to copy it, rename it, and you’re good to go. If, however, you’d rather bring selected components into your own project, you can also start from zero. For Rust newcomers who want to build everything themselves, the first goal is to get the project set up with all the required dependencies and with database migrations running. With that done, you can gradually pull in whichever features of the template you find useful.
- Set up the project
We begin by creating a regular Rust project. Use cargo to lay down the base of our template:
cargo new your-project-name
- Add axum and other dependencies
We’ll build a very simple application that lets you perform a few basic operations on 2 entities (cars and car parts). Later on, we’ll add redis caching, so that certain read operations return data from the caching layer when it’s there.
- Create db layer foundation
Sqlx persistence needs a database and tables. For the database server, we’ll use a docker compose script (more about it later) with postgres, and for the tables we need to create migrations in our project directory.
…sql up/down scripts
Add a database using docker-compose. Our docker compose file defines two services: the database server and a redis server for our cache.
docker-compose -f docker-compose.yaml up -d
- Add
dotenvyand create.envfile
To handle environment variables, we’ll use the widely used dotenvy lib. Create an .env file in the root directory of the project and put your entries for local development there. In production, these will of course be read from the secrets/globals or default values supplied by your cluster.
Env file content with db and cache url
- Migrate the data
With the db server running, you can migrate your data using the sqlx cli or, even better, make the migration run programmatically every time your application starts
pub async fn run_migrations(config: &Config) {
let db_pool = Arc::new(postgres::db_connect(config).await);
if let Err(e) = sqlx::migrate!().run(&*db_pool).await {
panic!("Failed to run database migrations: {:?}", e);
}
}
So far, we have a simple, largely empty web application, but our database is at least up and running. To turn it into a working microservice, we need to add some core functionality. First, we’ll organize the structure of the app so that it’s easy to extend and maintain as real features arrive. With the structure ready, we’ll add a few endpoints and bring in Swagger to simplify documenting our API.
Project Structure
This isn’t the ultimate guide to structuring a web service, but the approach has served me well (at least so far) and is still evolving. The code is split into modules, which establish a clear path for handling requests in the application, as shown below:
(Routes) -> controllers -> services -> repositories
routermodule: Here, Utoipa (for Swagger) is integrated with the routes of our application.appmodule: This is where everything is wired together via Axum’s layer/extension mechanism, connecting routes to the business logic underneath.
Extensions
Axum extensions make it possible to share state or data among middleware, handlers, and services. They come in particularly handy for managing shared resources such as database connections, configuration data, or business logic components. We add these layers in the app module like this:
pub async fn create_app(config: &Config) -> Router {
let _ = run_migrations(config).await;
let car_repository = Arc::new(create_car_repository(config).await);
let part_repository = Arc::new(create_part_repository(config).await);
let cache = Arc::new(create_cache(config).await);
router()
.layer(
TraceLayer::new_for_http()
// Create our own span for the request and include the matched path. The matched
// path is useful for figuring out which handler the request was routed to.
.make_span_with(|req: &Request| {
let method = req.method();
let uri = req.uri();
// axum automatically adds this extension.
let matched_path = req
.extensions()
.get::<MatchedPath>()
.map(|matched_path| matched_path.as_str());
info_span!("request: ", %method, %uri, matched_path)
})
// By default `TraceLayer` will log 5xx responses but we're doing our specific
// logging of errors so disable that
.on_failure(()),
)
.layer(Extension(car_repository))
.layer(Extension(part_repository))
.layer(Extension(cache))
}
Here, we register extensions for the car_repository, the part_repository, and a Redis cache. Our controllers’ route methods can then receive them as arguments, for example:
pub async fn view(Path(car_id): Path<i32>, Extension(repo): CarRepoExt, Extension(cache): CacheExt) -> Result<AppJson<Car>, AppError>
Extensions can be handed over to the service layer to run business logic, which makes sharing state efficient.
OpenAPI and Swagger
We define our endpoints with the Utoipa library. To hook Utoipa into Axum’s routing, we use a dedicated module with a router() builder function:
pub fn router() -> Router {
let app = OpenApiRouter::new()
.routes(routes!(utils::healthcheck))
.nest("/cars", car_routes())
.nest("/parts", part_routes());
let (router, api) = OpenApiRouter::with_openapi(ApiDoc::openapi())
.nest("/api", app)
.split_for_parts();
let router = router
.merge(SwaggerUi::new("/swagger-ui").url("/api-docs/openapi.json", api.clone()))
.merge(Redoc::with_url("/redoc", api.clone()))
// There is no need to create `RapiDoc::with_openapi` because the OpenApi is served
// via SwaggerUi instead we only make rapidoc to point to the existing doc.
.merge(RapiDoc::new("/api-docs/openapi.json").path("/rapidoc"))
// Alternative to above
// .merge(RapiDoc::with_openapi("/api-docs/openapi2.json", api).path("/rapidoc"))
.merge(Scalar::with_url("/scalar", api));
Router::new().nest("/", router)
}
Besides Swagger-UI, we’ve configured Redoc, RapiDoc, and Scalar. Keep whichever OpenAPI UI suits you best.
The endpoints are declared with Utoipa macros, and the compiler catches many possible mistakes:
/// Search all cars
///
/// Tries to get list of cars by query from the database
#[utoipa::path(
get,
path = "/search",
params(("name" = String, Query, description="Car Name")),
responses((status = OK, body = [Car])),
tag = CARS_TAG
)]
pub async fn search(Query(params): Query<CarQuery>, Extension(repo): CarRepoExt) -> Result<AppJson<CarList>, AppError> {
let cars = services::cars::search(repo.clone(), ¶ms).await?;
Ok(AppJson(cars))
}
When the application is up, every endpoint shows up in Swagger-UI, where you can test it interactively.
An example of the Scalar UI:
Error handling
Axum supports a number of error-handling strategies. To keep this template simple, I decided to use anyhow::Error and convert any error inside the application into a tuple holding an HTTP status code and a generic message. Detailed logs are kept internally for diagnostic purposes, while clients only get generic error messages. This approach strikes a balance between security and simplicity.
Below is our custom IntoResponse implementation for AppError:
impl IntoResponse for AppError {
fn into_response(self) -> Response {
// How we want errors responses to be serialized
#[derive(Serialize)]
struct ErrorResponse {
message: String,
}
let err = self;
let (status, message) = {
// Because `TraceLayer` wraps each request in a span that contains the request
// method, uri, etc we don't need to include those details here
tracing::error!(%err);
// Don't expose any details about the error to the client
(
StatusCode::INTERNAL_SERVER_ERROR,
"Something went wrong".to_owned(),
)
};
(status, AppJson(ErrorResponse { message })).into_response()
}
}
Plus a snippet that converts any anyhow::Error into our AppError whenever necessary:
impl<E> From<E> for AppError
where
E: Into<anyhow::Error>,
{
fn from(err: E) -> Self {
Self(err.into())
}
}
Wrapping Up
And that’s it – a simple starting point for a Rust microservice, prepared to scale together with your project. It isn’t the ultimate template, but it’s a beginning and, I hope, a step towards making Rust more approachable and practical for web services. Axum, paired with useful libraries such as Utoipa for OpenAPI integration, gives us a solid and flexible base to build upon.
Feel free to take the template, adjust it to your requirements, and make it yours. Whether you’re only getting started with Rust or want to bring it into your existing projects, the template is meant to get you going fast.
As with any good tool, you can mould and develop this setup as your needs evolve. Whether you deploy to a huge Kubernetes cluster or experiment on your own machine, I hope this template shows you what Rust can do beyond its reputation as a systems language. Rust web development still has a long way to go, but each new project and each experiment is an opportunity to expand what’s possible with it.
Do you have thoughts, ideas, or improvements? The template is still evolving, so don’t hesitate to get involved, try it, and share your suggestions. The Rust community is, after all, one of the language’s best assets, and building together is the best way to help it grow.
If Rust excites you as much as it does me, come to our one-day Rust conference on March 26, 2025. It’s an excellent chance to listen to talks by Rust experts, share your own ideas, and join the growing Rust community. I hope to see you there!
Happy coding!