1. Background
Mooncake is a one-stop collaboration platform for Dewu API. It has been a year since I started to be in charge of Mooncake in March 2022. Looking back on this year, Mooncake has gone through two versions in total:
1. Mooncake 1.0: A mock platform for front-end and client-side, mainly solving the data mock problem of interface callers
2. Mooncake 2.0: a one-stop document management platform that integrates yapi and mock for the front and rear ends, and solves the circulation efficiency of interface documents from both sides of supply and demand
The upgraded Mooncake product structure is as follows:
As shown in the figure above, we hope that Mooncake will be an important part of the R&D ecosystem of Dewu. In order to achieve this goal, Mooncake will continue to innovate and release many important functions, such as support for dyeing environment debugging, business iteration information reports, and support for Dubbo protocol. Mock, etc.; opened up RDC, EP, CMDB, gateway and other platforms. In addition, Mooncake also provides openAPI, which grows outward and supports platforms such as EP, DOP, APM, etc., so that developers can easily communicate smoothly through documents at all stages of research and development.
In this process, what exactly did Mooncake do, why did it do it, and what is the use of it after doing it? Let me briefly talk about my own thinking on these issues.
2. All the past is prologue
In 2002, Bezos issued a mandate to Amazon, which reads as follows:
From today, all teams must provide data and various functions in the form of service interfaces.
Teams must communicate through interfaces.
No other forms of interoperability are allowed: no direct links, no direct reading of other teams' data, no shared memory, no backdoors of any kind.
The only permitted means of communication is to call services over the network.
The specific implementation technology is not specified, and HTTP, Corba, PubSub, and custom protocols are all available.
All service interfaces must be designed to be public from the very beginning, without exception. That is to say, when designing an interface, it is assumed that the interface can be opened to outsiders, and there is no room for bargaining.
Those who do not comply with the above regulations will be expelled.
Thanks; have a great day!
The starting point of this instruction is that Bezos believes that interpersonal communication often leads to poor organizational execution , and his way to solve this problem is to systematically regulate dialogue between organizations through APIs.
In fact, this is nothing new under the current microservice architecture, and we use a lot of third-party open APIs, which are used to complete inter-system calls;
But at that time, how to make people accept this plan, actively participate in it, and prevent API flooding at the same time was a big problem. To this end, Bezos has established a set of indicator systems, and finally formed a set of positive continuous evolution and iterative cycles through incentives.
This index system can be understood as a kind of infrastructure at the company or organization level.
In 1934, during the Great Depression of the United States, one of Roosevelt's two major new policies to solve the economic crisis was Work-for-Work, which stimulated the balance between consumption and production through large-scale infrastructure construction.
The reason why Roosevelt chose to boost the economy through infrastructure construction is the same as Bezos' indicator system. In Lan Xiaohuan's book "Staying Inside Things: Chinese Government and Economic Development", it is mentioned that infrastructure has three characteristics:
1. Expand the scale of public services to generate economies of scale
2. Improve the efficiency of information communication and reduce the complexity of information
3. Strengthen the incentives for all parties to compete for resources
It can be seen that infrastructure can reduce costs and increase efficiency, and help organizations form a positive cycle.
Before March 2022, Dewu has accumulated tens of thousands of HTTP interfaces through the Yapi platform. This is the number of APIs that Dewu has grown naturally in the past seven years. This is already a huge number, but behind these http interfaces, There are also a larger number of rpc interfaces scattered in Yuque and Feishu, and a large number of interfaces have no document precipitation, and they are silently exerting their residual heat in history.
So how to standardize the documents, how to let more developers unify the interfaces, and how to make the huge amount of interface documents play a greater role, Mooncake has upgraded its services from three aspects:
1. Upgrade from a single mock service to a one-stop collaboration platform around interface documents, and users expand from front-end and client to server, test, front-end, and client
2. Focusing on the interface R&D life cycle, improve the efficiency of information communication and reduce the complexity of front-end and back-end communication through a series of tools such as plug-ins, Feishu messages, one-click mocking, and one-click configuration gateways
3. Associated rdc provides two-dimensional data dashboards of iteration and team, and stimulates internal competition through document quality statistics, thereby promoting the output of more efficient documents
Next, I will briefly review how Mooncake did this upgrade from the two levels of design and technology.
3. The design concept of Mooncake
For the upgrade of Mooncake, we followed Nielsen's ten design concepts:
1. System visibility principle
The system should give the user the appropriate feedback within the appropriate time, and always let the user know what is currently happening. — Nelson
It can be understood as including any operation of the user on the page. The system needs to give corresponding feedback to ensure that the user's status, changes, and content are visible during the operation, so as to help the user to interact Be guided in the right direction without wasting energy.
Mooncake responds to user operations through buttons and instant feedback of message prompts:
2. Close to the scene principle
The system speaks the user's language, with words, phrases, and concepts that the user is familiar with, not system jargon. Follow real-world conventions so that information appears in a natural and logical order. — Nelson
Users will get used to looking at problems with existing cognition in the real world. This existing cognition is a mental model built by users based on their own experience, knowledge and imagination.
This upgrade of Mooncake integrates Yapi and Mock. In addition to the integration of data and interaction at the bottom of the technology, it also retains the original interaction habits as much as possible, such as the habit of uploading documents through ideas, such as following documents, editing, and running. , type declaration to organize page tabs:
3. The principle of controllability
When the user chooses a function by mistake, the system needs to provide a clear "emergency exit" to let the user leave the state he does not want, and supports undo and redo without additional dialog boxes. — Nelson
In Mooncake, through the form of multiple tabs, it is convenient for users to open multiple interface documents without frequently refreshing the page:
4. Consistency principle
We should not make users wonder whether different statements, states, or operations are expressing the same thing, and the design must follow the conventions of the platform. — Nelson
Consistency can give users a unified cognition, help users quickly learn, remember and become familiar with the functions of the product, so as to establish a stable mental model for users. In order to ensure the unity of user experience among products, it is usually necessary to establish design specifications to ensure the consistency within the product. The consistency here includes visual consistency, behavioral consistency, and perceptual consistency.
In this upgrade of Mooncake, fonts, colors, size layouts, and component libraries all follow the design system specifications of Dewu:
5. The principle of error prevention
A better approach than error messages is to prevent errors through rigorous design: either eliminate error-prone conditions, or find these error-prone conditions and provide confirmation options before users take action. — Nelson
When the operation is irreversible, give the user a second chance to confirm to avoid the consequences caused by the user's misoperation:
6. System recognition trumps memory
By visualizing objects, operations, and options, the user's memory burden is minimized. Users do not need to remember information from one part to another in the dialog box. Instructions for system operations need to be easily found and obtained by users. — Nelson
It is impossible for users to remember too much information in the operation process. Mooncake provides 我的收藏and 最近访问helps students quickly find their frequently used project documents:
7. Flexibility and efficiency of use
Some shortcut functions, although ignored by novice users, may be used by expert users and help improve their efficiency. Therefore, the system needs to meet the needs of both novice users and expert users and allow users to operate frequently. — Nelson
This is actually a principle that is relatively easy to ignore in the design of B-end products. We often use products by default by relatively mature product users.
Mooncake's menu bar provides two modes of folding and unfolding, and will remember the user's last choice. For new students, the menu is expanded by default to facilitate understanding of the platform's functions; Maximize viewing area for easy reading:
8. Beautiful and simple design
Dialog boxes should not contain irrelevant or seldom-used information. Each additional piece of information in a dialog box means that the relative visibility of the main information is reduced. — Nelson
The dialog boxes of Mooncake reduce the complexity as much as possible, only do one thing at a time, only collect the most important data at a time, and provide drop-down boxes as much as possible to reduce user input:
9. Help users find, judge and fix errors
Error messages should be expressed in easy-to-understand language instead of code, accurately reflect the problem, and propose feasible solutions. — Nelson
10. The principle of humanized assistance
The information in the help documentation should be easily searchable, focus on the user's task, list specific steps, and not be too large. — Nelson
Mooncake provides global search, one-click access to Feishu Q&A group, and self-help help documents to help students quickly find documents and locate problems:
4. Mooncake's technical architecture
Before this upgrade, we investigated some industry practices on API management, which generally include two major components: tools and platforms.
4.1 Tool left
Tools are wheels, which solve current problems and are productivity tools;
Mooncake provides a set of tools:
1. The IDEA plug-in developed for java and the CLI tool developed for golang help developers upload documents quickly
2. Cover webpack, vite and browser proxy plug-ins to help front-end students realize data mock conveniently
3. Client proxy tools covering iOS and Android, helping clients to mock data
4. Cover the front-end and client-side packet capture tools to quickly generate mock data
4.2 Platform to the right
The role of the platform is to allow the resources in the platform to interact with each other through a series of resource integrations, and to create new productivity tools through continuous integration.
During the platformization of Mooncake, two principles were followed:
The first is multidimensionality. This concept comes from Poor Charlie's Book. Mooncake integrates platforms such as EP, CMDB, RDC, and gateways to maximize the value of documents and minimize the cost of API communication for R&D students.
The second is to divide and conquer and defeat each one. Architecture itself is a problem-solving process, and the problem is too complex to adopt a divide-and-conquer approach.
How to divide? Use the pyramid principle, think about data at the same time, and then split it according to the architectural theme. The Mooncake platform is divided into three parts: Documentation, Use Cases, and Mock, and upgrades and optimizations are carried out around these three parts. At the same time, according to the organizational structure and iteration, data statistics and analysis are carried out, and various indicators are provided to help R&D students measure the document quality of the project.
How to break it? Mooncake adopts a layered architecture, giving priority to solving the problem of documentation, and focusing on the depth of the document; after solving the problem of documentation, iteratively optimizes the upstream and downstream of the document and use cases, and broadens the breadth of the platform through openAPI.
5. The future of Mooncake
If Mooncake 1.0 is the Bronze Age and 2.0 is the Silver Age, then the next must be the Golden Age of Mooncake.
5.1 The Bronze Age
The 1.0 Mooncake covers all users of the Dewu front-end platform and nearly 50% of the client users.
5.2 The Silver Age
Mooncake in the 2.0 era integrates yapi+mock, and at the same time opens up platforms such as rdc, EP, and gateway platforms, and provides interface document services at various stages of the R&D process. A total of tens of thousands of interfaces have been deposited, covering 90% of the R&D students in the Dewu Technology Department , the NPS of the platform once reached 57%.
5.3 The Golden Age
There are still many problems in the current API construction and platform development:
1. Under the pressure of progress, some technical debt left over due to fluke psychology, such as switching between gateway environment and project environment, such as swagger timing scan, etc.
2. Some solutions that succumb to short-term goals, such as the simple version of the diff function, such as the simple version of the document migration function, etc.
3. Some lofty goals that were abandoned because the path was too long, such as dubbo debugging, such as document-driven development, etc.
In the future, Mooncake can do a lot more. Regarding API system construction, platformization, and openness, Mooncake will continue to promote product and technology innovation and upgrades, and provide better products and services for small partners in the technology department.