Speaking of micro services, most of the people in the technology circle can talk and laugh and talk. It’s true that technology is changing so fast and tools and frameworks are springing up that we can now easily and easily build microservices tailored to our business needs.
A microservice is a business-focused service design concept in which each service has its own business function, an API (most commonly HTTP) that is open to the outside world, and an application consisting of one or more microservices.
Cross-language implementations are true, but only in terms of programming language dimensions. Cross between people is not so convenient, huashan you send door has Restful calls, I wudang Thrift (http://thrift.apache.org/), a recruit walk the world. What! Shaolin sent next door said their king kong Protobuf (https://developers.google.com/protocol-buffers/) and you are…
Don’t make trouble, if we all write their own martial arts secret book easy to understand, isn’t everyone can practice hundreds of martial arts?
It all starts with README
* * * * * * * * * *
When the Boss asks you to build a new project, I’m sure you’re lucky because you’re greeted with a fresh start, not some old project left behind by some departed predecessor.
If your intuition is with me, then I’m sure you appreciate the opportunity to code, so you start building your blank project on GitLab using your familiar scaffolding tools.
What? ! That’s it? No, no, no, after that, don’t monkey in a hurry to write code, relax, let’s touch a README, imagine your project architecture should be how to, provide roughly what function, for others to call the entrance of the code should be designed to be what kind, what are your required for the project technology stack, can even think of Todo list, and so on.
These can be filled into your README first, and if you can, you can even use some prototyping tools (ProcessOn, Pencil, Cacoo) to create architectural sketches, sequence diagrams, or, if you really don’t have the right tools, try using raw pen and paper to take a picture.
Figure: A good sample README
A nice README makes it easy for the rest of the team to quickly understand the core features of your project, making it enjoyable to watch!
When you write a README, you feel like you’re writing a great project, right? Sometimes you need to set yourself a small goal, give yourself some sense of accomplishment, and continue with your code with a sense of joy.
Elegant code style and comments
★★★★ plugin for Google Java Formatter
Code style.
Maintaining good code style is always a good thing, especially on a collaborative team where it’s hard to imagine how confusing each other’s code style can be.
Modern integrated development environments make it much easier to keep code clean. If you are lazy to configuration, so here is a good choose Google Java Formatter (https://github.com/google/google-java-format). Install it, and your code will always be Google-like.
Always keep pace with your team, of course.
If your team has a severe obsessive-compulsive disorder, so like CheckStyle (https://github.com/checkstyle/checkstyle), a tool will be suitable.
In addition to code style, a well-designed Restful API is a must if you use Restful. Here recommend nguyen other teacher RESTful API design guidelines (http://www.ruanyifeng.com/blog/2014/05/restful_api.html).
About the comments
Writing comments is painful, but also helpful. You don’t necessarily need to cover most of the code perfectly, which is expensive and doesn’t make much sense.
Figure: Code comments (from mysterious programmers)
-
Self-documentation makes your code visible without comments. This requires that you pay attention to good naming and design when coding.
For example, if you need a method with a timer time parameter, if the parameter name is time, the caller will wonder whether to pass milliseconds or seconds. Make it timeInSeconds or split it into time + timeUnit.
For example, if your implementation class needs additional configuration items, think about how bad it would be if the structure were a Map, which would confuse the user. At this point, you can define a proprietary configuration object, or the initialization process into a Builder, etc.
Always think about the guys who will maintain your code in the future, and you in the future.
-
Exposed code
Such as exposed interfaces, utility classes and so on. Because it’s often called by someone else. Write detailed instructions in these places and let your friends have fun with them.
-
Core or obscure parts
You can ignore most code comments because 80% of the code is readable in a matter of minutes. There are only a few that are important or too complicated to understand, so be sure to describe them.
-
Helps document generation
If your comments are recognized by the build tool and can do something to automate document generation, be sure to comment them appropriately. Configure these little tool is very simple, such as configuration maven – javadoc – plugin (http://maven.apache.org/plugins/maven-javadoc-plugin/) can generate a large amount of javadoc. You can even fix some comments automatically for you, so why not?
Share your work
★☆☆☆
When you finally write the initial code, your microservice is finally up and running. But you don’t have the time to seriously write an API manual. How do you give your team a general idea of your API?
If you are using binary protocols such as Thrift and Protobuf, there is no great way to do this. It is recommended to include a lot of comments in the DSL description file because everything is based on those definition files.
If you use mainstream REST, then congratulations, thriving Ecology has plenty of tools to do it for you.
Comparison entry-level, do you have a Postman (https://www.getpostman.com/) or Paw (https://paw.cloud/, collect fees) tool can help you debug, these tools also have a share capability at the same time, you can share to the front, test group of colleagues.
Photo: Postman at a glance
If you have a larger team, you may need to create a special page for Confluence. Or use a specialized API tool, like the RAP used by my team, to do more advanced things besides basic sharing.
Figure: RAP overview
Write your API carefully
★★ ★☆☆
Finally, after all the testing and bugfixes, your microservice is ready for public deployment. In the midst of your excitement, you’re smart enough to figure out that you need some way to elegantly express your API.
Bingo! Pick the right tool and get started! The famous Swagger, for example, with some basic YAML, will soon be able to map your API.
Picture: Swagger editor
So you soon have a Swagger (http://swagger.io/) file that would be great for generating some UI, or whatever.
What? ! You think writing YAML is too tedious and you don’t like it?
We also have RAML (http://raml.org/) or API Blueprint (https://apiblueprint.org/), and so on a lot of tools.
What? ! You still find it unacceptable to have no GUI??
Ok, so I recommend a more friendly tool like APIMATIC, where you can import and export other formats, as well as write using its GUI. Does that make you feel better?
Figure: APIMATIC editor at a glance
With these tools, it is easy to automatically generate document HTML for everyone to query when they use it.
The author’s current habits are:
-
Write apis using APIMATIC
-
Export to API Blueprint
-
Generate document HTML using Aglio
Photo: Final result
Finally, I wish you can write their own micro service documents wonderful! I have limited ability, if you have hidden good tools, good method, also hope to share out oh.
The author information
Weiwei CAI is a member of LeapCloud MaxLeap’s Data Analysis team. He graduated from Tongji University and has been working in Java development for many years. He has been engaged in the design and development of ETL, AdHoc report, vertical crawler, App making cloud service, dynamic user clustering and other products. He has dabbled in various aspects of the Internet for many years.