目录 (Table of Contents)

• Introduction
  介绍

• Building the Skeleton

  建立骨架

  - HTTP Endpoints

  -HTTP端点

  - Swagger

  -昂首阔步

  - Prometheus & Grafana

  -普罗米修斯与格拉法纳

  - Logging

  -记录

  - CICD Integration

  -CICD整合

• Conclusion
  结论

介绍 (Introduction)

Custom frameworks are built and used in many organizations to make life easier for engineers. Any such framework is supposed to deliver a bundle of necessary features that we expect in every application, or as the organization demands, to make it standardized and reliable. This can range from specific logging format, using or restricting certain open source software, to enforcing versions, build tools or even deployment strategies. Frameworks (and libraries) in general come as a blackbox, and the engineer is not expected to change its internal working. Rather to simply use it by fitting the application being built into it (if it’s a framework) or import the packages/classes into the code and invoke them (if it’s a library).

C tomtom框架已在许多组织中构建和使用，以使工程师的工作变得更轻松。 任何这样的框架都应提供我们期望在每个应用程序中或根据组织的要求提供的一系列必要功能，以使其标准化和可靠。 范围可以从使用或限制某些开源软件的特定日志记录格式到执行版本，构建工具甚至部署策略。 框架(和库)通常是一个黑匣子，工程师不应更改其内部工作。 而不是简单地通过适合内置在其中的应用程序(如果是框架)来使用它，或者将包/类导入代码中并调用它们(如果是库)。

While this sounds nice, more often, if the framework is not designed properly, it can get unstructured, or outdated. An example would be a custom framework which might work with Tomcat but not with Spring Boot, or something that works with Tomcat 7.x but not with Tomcat 9.x. To make things worse, if the framework keeps on adding new features without focusing on backward compatibility, or enforces new standards, then you have made a beast out of it which is no longer in control. At this point the cost for an engineer to fit her code into this is more than implementing her own minimal framework. There is a line we need to draw when building such frameworks and I often ponder on the question, how much is too much?

虽然听起来不错，但通常情况下，如果框架设计不当，它可能会变得结构化或过时。 一个示例是自定义框架，该框架可能适用于Tomcat，但不适用于Spring Boot，或者适用于Tomcat 7.x，但不适用于Tomcat9.x 。 更糟糕的是，如果框架继续增加新功能而不关注向后兼容性，或者强制执行新标准，那么您就从中失去了控制力。 在这一点上，工程师将其代码适合于此的成本比实现自己的最小框架要高。 建立这样的框架时，我们需要划清界限，我经常思考这个问题， 多少是太多？

To begin with, a framework needs to be maintainable. We might be tempted to include a ton of features and that obviously with good intentions. However, do all my users need all the features? Am I enforcing a specific feature? What if one of the applications have a specific need which is blocked by this enforcement? Also, is it a better idea to provide a template, from which engineers can pick and choose, rather than provide a black box of one size fits all.

首先，框架必须是可维护的。 我们可能会尝试包含大量功能，并且显然带有良好的意图。 但是，我所有的用户都需要所有功能吗？ 我要执行一项特定功能吗？ 如果其中一个应用程序有特定需求但被该强制执行阻止了怎么办？ 另外，提供一个可供工程师选择的模板，而不是提供一个适合所有人的黑匣子是一个更好的主意。

More often, we come across internal frameworks which force an engineer to use log4J (instead of slf4j) and spits out the logs at a specific location and format which can’t be overridden. Or we see that a core feature of the framework is using a deprecated dependency, or a shaded dependency which can’t be upgraded.

更常见的是，我们遇到了一些内部框架，这些框架迫使工程师使用log4J (而不是slf4j )并在无法覆盖的特定位置和格式处吐出日志。 或者，我们看到该框架的核心功能是使用不推荐使用的依赖项或无法升级的阴影依赖项 。

使用自定义框架的优点 (Pros of using a custom framework)

• Get out of the box support without the need to understand how it works
  获得即时可用的支持，而无需了解其工作原理
• No need to customize and add dependencies. Just integrating the framework is enough
  无需自定义和添加依赖项。 仅仅集成框架就足够了

使用自定义框架的缺点 (Cons of using a custom framework)

• One size fits all means, you also pull in features that you do not need

  一种尺寸完全适合您，您还可以使用不需要的功能

• In case, a dependency is deprecated, you have no way to override that unless you dig in, and even then, you might not be able to fix a shaded dependency
  如果不赞成使用某个依赖项，除非您进行深入研究，否则您将无法覆盖它，即使那样，您也可能无法修复阴影的依赖项
• If the framework enforces restrictions, you are out of luck. You need to reach out to the team who is maintaining it, to get it working
  如果框架强制实施限制，那么您将不走运。 您需要联系维护它的团队，以使其正常运行

• Unless it’s properly designed, maintainability would be an issue, and the more features it incorporates, the harder it gets to maintain. The ‘How much is too much?’ problem

  除非设计得当，否则可维护性将成为一个问题，并且它包含的功能越多，维护就越困难。 “多少钱太多了？” 问题

• There is no way an engineer can exclude items she does not need, or incorporate things she needs without working with the team that supports the framework
  工程师无法在不与支持框架的团队合作的情况下排除她不需要的项目或合并她需要的东西

Hence, unless there are specific needs, may a times, the cons outweigh the pros of a custom framework. When mulled upon carefully, we also observe that if building a template, the above pros become cons and vice versa.

因此，除非有特定的需求，否则有时可能会超出自定义框架的优点。 在仔细考虑之后，我们还观察到，如果构建模板，上述优点将变得不利，反之亦然。

建立骨架 (Building the Skeleton)

Faced with all these questions, we embarked on an effort to build something that is just right. One that has all the things we need, and yet engineers can pick and choose. This shouldn’t be a library or a framework but rather a template. Teams can clone this template and remove things that are not relevant to their use cases. People should feel free to use, contribute, and let other know about this template. For now, we want to keep it Inner-Sourced (if not Open-Sourced in the future).

面对所有这些问题，我们开始努力构建正确的东西。 一个拥有我们所需所有东西的工具，但工程师可以选择。 这不应该是一个库或框架，而应该是一个模板。 团队可以克隆此模板并删除与用例无关的内容。 人们应该随意使用，贡献并让其他人知道此模板 。 目前，我们希望将其保留为“内部来源”(如果将来不再开源)。

We decided to call it the Service Skeleton and build it in the language most commonly used in the ‘Search Organization’ — Java. This is a simple collection of nifty and useful tools that integrate nicely with each other. For that purpose, we decided to use Spring Boot. The goal here is not to reinvent the wheel. Rather provide easy integration points to spin off a new micro service quickly. Spring boot seemed to be the obvious choice due to its offering of almost every thing we needed to get started.

我们决定将其称为服务框架，并以“搜索组织”中最常用的语言-Java进行构建。 这是一个精巧而有用的工具的简单集合，它们很好地相互集成。 为此，我们决定使用Spring Boot 。 这里的目标不是重新发明轮子。 而是提供简单的集成点，以快速剥离新的微服务。 由于Spring Boot提供了我们入门所需的几乎所有东西，因此它似乎是显而易见的选择。

Spring boot works easily with Rest/HTTP service with the need of zero boiler plate code. It comes packaged with logback for logging purposes, and actuator-prometheus integration for metrics exposure. It also integrates very easily with Swagger. The application runs inside a docker container, which in turn is managed and orchestrated by Kubernetes. For smoother operation, the application needs to expose logs and metrics to external systems like Splunk and Grafana, along with its own HTTP endpoints. We will go over these now.

Spring Boot可以轻松地与Rest / HTTP服务一起使用，而所需的模板代码为零。 它随机配的logback进行日志记录，并执行器普罗米修斯集成度量曝光。 它也很容易与Swagger集成。 该应用的内运行搬运工容器，而这又是管理和协调Kubernetes 。 为了使操作更流畅，应用程序需要将日志和指标公开给Splunk和Grafana等外部系统，以及其自己的HTTP端点。 我们现在将讨论这些。

HTTP端点 (HTTP Endpoints)

Since most of the applications are micro services exposing HTTP endpoints, it gives a template of Controller-DTO-Service integration using Spring boot and sample test cases, something most commonly used in any micro services.

由于大多数应用程序都是暴露HTTP端点的微服务，因此它提供了使用Spring Boot和示例测试用例(所有微服务中最常用的一种)的Controller-DTO-Service集成模板。

It is important to keep in mind that a micro service is already broken down based on domain driven design. There should be no further need to have sub-domains inside the micro service. The code should simply be grouped based on its responsibility (controller/service/repository/DTO). The external facing DTOs might be worth being a separate artifact, but that is a separate discussion and beyond our scope. It’s okay to have other logical groupings as you need. However, unless there is a specific need, you should not create sub-modules in your repo.

重要的是要记住，基于域驱动的设计 ，微服务已经被分解。 微服务内部无需再有子域。 该代码应仅根据其职责(控制器/服务/存储库/ DTO)进行分组。 面向外部的DTO可能值得作为单独的工件，但这是单独的讨论，超出了我们的范围 。 可以根据需要进行其他逻辑分组。 但是，除非有特殊需要，否则不应在存储库中创建子模块。

昂首阔步 (Swagger)

With HTTP endpoints, there is a need to define contracts and communicate that with teams who will be using this service. That means documenting these on Confluence, Github or some other location. Over time, these docs seem to get out of sync and even fall through the cracks. It would be nice if the documentation is integrated right with the code and there is also an easy way to test those out. Enter Swagger for contract documentation.

对于HTTP端点，需要定义合同并与将使用此服务的团队进行通信。 这意味着要在Confluence，Github或其他位置记录这些文件。 随着时间的流逝，这些文档似乎变得不同步，甚至陷入了困境。 如果文档与代码正确集成在一起，并且还有一种简便的方法可以测试这些文档，那就太好了。 输入Swagger作为合同文件。

普罗米修斯和格拉法纳 (Prometheus and Grafana)

It is important to understand the traffic volume, latency, CPU/memory usage, scalability, throughput and availability among other things to ensure the application is operational. Our devOps teams have Grafana infrastructure which expect applications to provide these metrics which can be displayed as graphs. The common and standard format supported is that of Prometheus. The Service Skeleton exposes metrics in Prometheus format and provides examples to implement custom metrics.

重要的是要了解流量，延迟，CPU /内存使用率，可伸缩性，吞吐量和可用性等，以确保应用程序正常运行。 我们的devOps团队拥有Grafana基础架构，希望应用程序提供这些指标，并可以图形形式显示。 支持的通用和标准格式是Prometheus 。 服务框架以Prometheus格式公开指标，并提供示例以实现自定义指标。

记录中 (Logging)

Another operational aspect is to trouble shoot issues and go back in time to see what happened. For this we need logging. Unlike old days, we can’t have logs written to physical files on the same ‘hardware’ where the application is running. We are on the cloud and inside a container, the logs from all the instances of the container need to go to a central log management system. We use Splunk for that. The application simply writes logs to console, and the devOps team takes care of ensuring that the logs end up in Splunk. We are not going to focus on how that is done, rather, we ensure that the Service Skeleton writes the logs in the right format. We use logback, that comes bundled with Spring Boot. In this context, we are also leveraging spring profiles, where local profile generates standard single color-coded log lines for easy debugging should you need to run it on your local computer/IDE. While the deployments on Kubernetes, that generate logs for Splunk, do so in json format for easy filtering.

另一个操作方面是对问题进行排查并及时返回以查看发生了什么。 为此，我们需要记录。 与过去不同，我们无法将日志写入应用程序运行所在的同一“硬件”上的物理文件中。 我们在云中，并且在容器内部，该容器所有实例的日志都需要转到中央日志管理系统。 为此，我们使用Splunk 。 该应用程序只需将日志写入控制台，devOps团队会确保确保日志最终存储在Splunk中。 我们将不着重于如何完成操作，而是确保服务框架以正确的格式写入日志。 我们使用logback ，它与Spring Boot捆绑在一起。 在这种情况下，我们还利用spring概要文件 ，其中，如果需要在本地计算机/ IDE上运行它，则本地概要文件会生成标准的单色编码日志行，以便于调试。 在Kubernetes上的部署为Splunk生成日志时，以json格式进行部署以便于过滤。

CICD整合 (CICD Integration)

Since all the deployments would happen on pods running on Kubernetes, we even fitted a template of the Docker file and a sample CICD pipeline for the Service Skeleton.

由于所有部署都将在Kubernetes上运行的Pod上进行 ，因此我们甚至为Service Skeleton安装了Docker文件的模板和示例CICD管道。

So what we built is not a framework or library, rather, is a collaboration of things an engineer needs in the organization to kick start a project, without digging out the integration pain-points. Just like with Spring, you don’t need to worry about parsing the HTTP Request anymore, with this, you do not need to lay down the bones. Go ahead and add the muscles, the bones will start to move, since they are already there. Exactly the reason, we call it a Service Skeleton.

因此，我们构建的不是框架或库，而是工程师在组织中启动项目所需的东西的协作，而无需挖掘集成的痛点。 就像使用Spring一样 ，您不再需要担心解析HTTP请求，因此，您无需放下骨头。 继续并添加肌肉，骨骼将开始移动，因为它们已经在那里。 确切的原因，我们称其为Service Skeleton 。

结论 (Conclusion)

Every time we build something new, we need to draw our boundaries. While it is tempting to add new flavors into the broth, adding too many of them may overwhelm the taste, and make your dish less appealing. It is also important to understand the use case of what we are building.

每次我们构建新内容时，都需要划定界限。 虽然很想在肉汤中添加新的风味，但添加太多的风味可能会使味道不堪重负，并使您的菜吸引力降低。 了解我们正在构建的用例也很重要。

As we can see above, the Service Skeleton, while providing the tooling for integration with Swagger, Prometheus, Grafana, Logging and CICD pipeline, also gives an engineer the option to include or remove features. If someone has a specific need to use a different logger, or not use Metrics endpoint, they can do so easily.

正如我们在上面看到的那样， Service Skeleton在提供与Swagger，Prometheus，Grafana，Logging和CICD管道集成的工具时，还为工程师提供了包括或删除功能的选项。 如果有人特别需要使用其他记录器，或者不使用Metrics端点，则他们可以轻松地做到这一点。

We want to empower the engineer to quickly spin off a new service, but at the same time ensure there is enough flexibility for her to fit her needs and customize. The best thing you can do to achieve this is not to build a library or a framework, but rather a skeleton and let the engineer add muscles to it.

我们希望授权工程师Swift推出一项新服务，但同时要确保有足够的灵活性来满足她的需求并进行个性化定制。 要实现这一目标，最好的办法不是构建库或框架，而是构建骨架，并让工程师为其增加力量。