Microservices – How to Structure in Your Repository

Architecturemicroservicesrepositoryrepository-pattern

I am assigned to a project where we have about 20 micro-services. Each of them is in a separate repository without any references to any other, apart from one Nuget package where we maintain some generic code like math functions. Each service reference the others by endpoints.

The advantage of this is:

Each service is highly independent. (In reality this point is up for discussion, as a change to the API of one service is likely to effect multiple others)
Best practice – according to people I have talked to

The disadvantage are:

No code re-use.
The some DTO objects are defined multiple times (maybe up to 10ish)
Each ServiceCommunication helper class that wraps the endpoints of a service for ease of use are duplicated multiple times, once for each repo.
API changes are hard to keep track of, often we see the failure in Test/Production

I think the following is a better way to structure the project:
One repo.
Each micro-service provides a Server.Communication helper class that wraps the endpoinds and a selection Server.Dto types which the Server.Communication class returns from its API calls. If an other service whishes to use it, it will include this.

I hope I explained the problem well enough. Is this a better solution that will address some of my issues or will I end up creating unforeseen problems?

Best Answer

No code reuse is usually understood as a selling point for microservices!

the microservices can be developed and deployed independently
different microservices can use different technologies, in particular different programming languages

If this does not seem like an advantage – in particular if all microservices are developed by one team, using one technology stack, and deployed together – then maybe you don't need microservices, but a set of libraries. And you could maintain all libraries/services within one monorepo.

If we ignore any scalability arguments for a moment, libraries are vastly preferable over microservices. A microservice API is effectively dynamically typed, which can be a source of errors – just as you experienced. In contrast, library APIs are usually statically typed, which can prevent a whole class of errors via compile-time type checking. Also, Intellisense is nice. Libraries that run within the same process tend to be much easier to use than distributed systems, which have their own challenges especially around network failures, consistency, and distributed transactions.

Using a microservice architecture means that you accept these drawbacks because microservices allow you to address even bigger problems, such as organizational scalability (let different teams develop and deploy their services independently) and technical scalability (scale different parts of the system separately).

There is possible middle ground between libraries and microservices that can make your life a bit easier.

For example, a microservice can provide a client library for connecting to that microservice. This library handles connection details and provides a set of data transfer objects. If designed correctly, older library versions are still able to interact with newer versions of the microservice, which allows them to be updated somewhat independently. However, this requires that all users of that microservice use the same programming language, and that these users can upgrade their client library within a reasonable time frame. Such an approach may be useful for a team that started using microservices without understanding the implications, but is usually not viable if you are using microservices for their organizational scalability benefits.

A milder version of this is to use a service description language that provides a language-agnostic API definition. Clients can then use code generation tools to generate DTOs and connection libraries in their programming language. This successfully decouples the services from another, while avoiding the possibility of API mismatch errors. Having to work in this service description language also makes it more difficult to accidentally break backwards compatibility. But it does require you to learn additional tools, and the generated code can be awkward to use. This is usually the way to go in more enterprisey environments.

You may also be able to apply advanced testing methods to rule out API mismatch, e.g. record/replay integration tests: first, you run a client's test cases against a real microservice and record the requests and responses. The artifact of this recording is shared by the client and the microservice. The recordings can then be used in the client tests to provide a mock microservice that replays the canned responses. The recordings are also used by the microservice to verify that the service continues to provide the same responses. Unfortunately, updating these recordings to account for changes can be difficult. The recordings can also be very fragile, e.g. if irrelevant metadata like exact dates is not sanitized. I'm currently working on transitioning a similar test suite, but the fragility of depending on exact recorded responses makes this incredibly hard.

Related Solutions

Microservices Security – Authorization Best Practices

No, you are not using tokens correctly.

The idea is that you have an Auth service which issues tokens and Resource services which can validate the token and read the claims it contains. So the rather than forwarding the bearer token to the auth service each time the flow should be as follows

Client -> Auth : please give me a token, here is my username and pass
Auth -> Client : here is a token I have signed it with my private key and it contains the claim "i am an Accounting Agent"

then

Client -> Resource : hi, please give me a list of accounts, here is my token
Resource -> Client : I have checked the signature on your token using the Auth services public key. so I know I can trust your claim that you are an Accounts Agent. Here is the list of accounts

then

Client -> Resource : Please delete this account, here is my token
Resource -> Client : sorry Account Agents are not allowed to delete accounts

This flow prevents the Auth service becoming a performance bottleneck and leave the various microservices to decide if Claim X can do Operation Y

Roles

To address your second question about roles and permissions. At the end of the day a service has to have a set of Roles or Permissions that it knows about. eg you have to actually code something like:

If(users.Role != "RoleX")
{
    return "Access Denied!";
}

Rather than have a whole list of different permissions, 'canEditAccounts' ,' canEditCustomers', 'canDeleteAccounts'... etc etc the modern approach is to instead have a shorter list of Roles 'AccountingAgent' which essentially act as a set of permissions.

If a third party consumes your services though they will have to use the roles that the service knows about. This means that they are stuck with the level of granularity that you provide in your Roles.

ie If your Accounting Agent does too little and your Accounting Manager does too much for your third parties needs you are stuck.

One way around this is to have a dynamic mapping between Roles and Permissions. Have your service know about permissions and query what permissions a role has.

You can then allow your third party consumers to create their own roles, selecting the permissions they want each to have

Microservices Architecture – Approaches to Splitting a Monolithic Application

The preferred approach will depend on several factors. At my company, we use both approaches (using Hermes rather than a queue for asynchronous communication) since they both have their advantages in certain situations.

The main factor of interest is what requirements you have on data freshness for a certain pair of services. Basically, asynchronous communication (such as using a queue) has the benefit of causing less coupling between services and potentially allowing better throughput since you can schedule data transfer at a convenient time, repeat failed transmissions as many times as you like and so on. The downside is that things happen asynchronously so there is always some lag involved as one service sees stale data before it gets an update from the other. There may also be considerable disk and CPU resources required if you want to duplicate a large database in each service.

Also, take into account that in a distributed system, things as simple as "making a copy of data in another place" get tricky. If you have one instance of application A and one instance of application B, and everything happens synchronously, you can make and keep in sync a true copy of all data from service A to service B. But when you have N instances of A talking to M instances of B, and to make matters worse, communication is asynchronous, it's really hard to keep an up-to-date copy. For example instance A1 may update a document, then instance A2 also updates the same document and now you have two update events racing to reach instances B1 and B2 which may receive and apply them in any order. It's a big topic but the take out is complexity grows a lot.

So, here are a few concrete examples of when using each of the approaches may be the better choice:

You have an authorization service with information about users and their access rights. Here, REST is preferred: you want any change (such as removing a user's permissions) to be active immediately. For security reasons you also don't want to make any copies of users' personal information or credentials.
A service displays advertising for certain products your web shop is selling. Each product's ad contains a name, a short description and a link URL. Assuming the number of advertised products is not huge, making a copy via asynchronous communication may be preferable. Products are not updated very often and if they are, adding a delay of a few minutes before the change is visible in the ads is acceptable. Your ad server may index ads in some special format tuned for performance of ad serving, and services are loosely coupled: your ad service is not increasing the load on your main product database as much as if it were using REST requests.
Your shop's listing pages show the products you sell. Here, you probably want to query the product database service directly via REST. When you edit a product, you want the change to be visible on your shop's page as soon as possible. The whole product database is probably quite big so duplicating it in the frontend service would be a large hardware cost.

As you see, there are good use cases for both approaches, and in a large system you probably have to settle on using a hybrid approach of using #1 or #2 depending on the situation.

Best Answer

Related Solutions

Microservices Security – Authorization Best Practices

Microservices Architecture – Approaches to Splitting a Monolithic Application

Related Topic