Documentation

• 1: 1. Product Introduction
• 1.1: 1.1 Introduction and Use Cases
• 1.2: 1.2 Industry Background
• 1.3: 1.3 Architecture Introduction
• 1.3.1: 1.3.1 Architecture Principles
• 2: 2. Quick Start
• 2.1: 2.2 Module Operations
• 3: 3. Video Tutorials
• 4: 4. User Manual
• 4.1: 4.1 Base Access
• 4.1.1: 4.1.1 SpringBoot or SOFABoot Upgrade to Base
• 4.2: 4.2 Module Access
• 4.2.1: 4.2.1 Upgrade to Module from existing SpringBoot or SOFABoot
• 4.2.2: 4.2.2 Creating Modules Using Maven Archetype
• 4.2.3:
• 4.3: 4.3 Module Development
• 4.3.1: 4.3.1 Coding Standards
• 4.3.2: 4.3.2 Module Slimming
• 4.3.3: 4.3.3 Module Startup
• 4.3.4: 4.3.4 Module Communication Module to Module and Module to Base Communication
• 4.3.5: 4.3.5 Module Local Development and Debugging
• 4.3.6: 4.3.6 Reusing Base Data Source
• 4.3.7: 4.3.7 Reusing Base Interceptors
• 4.3.8: 4.3.8 Thread Pool Usage
• 4.3.9: 4.3.9 Multiple Configurations for Modules
• 4.3.10: 4.3.10 Multimodule Integration Testing
• 4.3.11: 4.3.11 Static Merge Deployment
• 4.3.12: 4.3.12 Officially Supported Middleware Clients in Modules
• 4.3.13: 4.3.13 Koupleless Configuration
• 4.3.14: 4.3.14 SOFAArk Key User Documentation
• 4.4: 5. Module Controller V2 Operation and Maintenance
• 4.4.1: 5.1 Module Release
• 4.4.2: 5.2 Module Release Operations Strategy
• 4.4.3: 5.3 Health Check
• 4.4.4: 5.4 Deployment of Module Controller V2
• 4.4.5: 5.5 Module Information Retrieval
• 4.4.6: 5.6 Error Codes
• 5: 6. Participate in the community
• 5.1: 6.1 The philosophy of openness and inclusivity
• 5.2: 6.2 Communication channels
• 5.3: 6.3 Community Contributions
• 5.3.1: 6.3.1 Local Development Testing
• 5.3.2: 6.3.2 Completing the First PR Submission
• 5.3.3: 6.3.3 Document, Issue, and Process Contribution
• 5.3.4: 6.3.4 Organizing Meetings and Promoting Operations
• 5.4: 6.4 Community Roles and Promotion
• 5.5: 6.5 Technical Principles
• 5.5.1: 6.5.1 SOFAArk Technical Documentation
• 5.5.2: 6.5.2 Arklet Architecture and Api Design
• 5.5.3: 6.5.3 Runtime Adaptation or Best Practices for Multi-Module Deployment
• 5.5.3.1: 6.5.3.1 Koupleless Multi-Application Governance Patch Management
• 5.5.3.2: 6.5.3.2 Introduction to Multi-Module Integration Testing Framework
• 5.5.3.3: 6.5.3.3 Adapting to Multi-Module with Dubbo 2.7
• 5.5.3.4: 6.5.3.4 Best Practices for Multi-Module with ehcache
• 5.5.3.5: 6.5.3.5 Logback's adaptation for multi-module environments
• 5.5.3.6: 6.5.3.6 log4j2 Multi-Module Adaptation
• 5.5.3.7: 6.5.3.7 Module Use Bes
• 5.5.3.8: 6.5.3.8 Module Using Dubbo
• 5.5.3.9: 6.5.3.10 Introduction to the Principle of Class Delegation Loading between Foundation and Modules
• 5.5.3.10: 6.3.5.11 What happens if a module independently introduces part of the SpringBoot framework?
• 5.5.4: 6.5.4 Module Split Tool
• 5.5.4.1: 6.5.4.1 Semi-Automated Split Tool User Guide
• 5.5.4.2: 6.5.4.2 Is it too difficult to collaborate on developing a monolithic application? Koupleless brings Split Plugin to help you streamline and improve the efficiency of collaborative development!
• 5.6: 6.6 ModuleControllerV2 Technical Documentation
• 5.6.1: 6.6.1 ModuleControllerV2 Architecture
• 5.6.2: 6.6.2 ModuleControllerV2 Scheduling Principles
• 5.6.3: 6.6.3 Core Process Timeline
• 6: 6.7 FAQ
• 6.1: 6.7.1 FAQ List (please search your problem in this page)

1 - 1. Product Introduction

1.1 - 1.1 Introduction and Use Cases

Introduction

Koupleless is a modular Serverless technology solution that enables ordinary applications to evolve into Serverless development mode at a relatively low cost, allowing code and resources to be decoupled and easily maintained independently. At the same time, it supports capabilities such as second-level build deployment, merged deployment, and dynamic scalability, providing users with the ultimate development and operation experience, ultimately helping enterprises achieve cost reduction and efficiency improvement. With the increasing digital transformation across various industries, enterprises are facing more and more pain points in terms of development efficiency, collaboration efficiency, resource costs, and service governance. Let’s explore these pain points one by one and see how they are addressed in Koupleless.

Use Cases

Pain Point 1: Slow Application Build and Deployment or Tedious SDK Upgrades

Traditional application image building usually takes 3-5 minutes, and deploying code to start completion also takes 3-5 minutes. Developers have to undergo multiple 6-10 minute build and deployment waits each time they verify or deploy code changes, severely impacting development efficiency. Additionally, each SDK upgrade (such as middleware frameworks, RPC, logging, JSON, etc.) requires modifying all application code and re-building and deploying, causing unnecessary disruption to developers.
By using Koupleless Universal Base and accompanying tools, you can cost-effectively split applications into “base” and “module”. The base encapsulates common SDKs of the company or a specific business department, and base upgrades can be handled by specialists without affecting business developers, who only need to write modules. In our currently supported Java technology stack, a module is a SpringBoot application code package (FatJar). However, the SpringBoot framework itself and other enterprise dependencies are pre-loaded and warmed up by the base at runtime. Each time a module is deployed, it finds a base with pre-heated SpringBoot for hot deployment, similar to AppEngine, enabling users to achieve 10-second build and deployment for applications and seamless SDK upgrades.

Pain Point 2: High Resource Costs for Long-tail Applications

In enterprises, 80% of applications serve less than 20% of the traffic. Along with business changes, enterprises have many long-tail applications. These long-tail applications have CPU utilization rates of less than 10% for an extended period, leading to significant resource waste.
By using Koupleless merged deployment and accompanying tools, you can cost-effectively achieve the merged deployment of multiple applications, solving the problem of excessive fragmentation of enterprise applications and the resource waste caused by low-traffic businesses, thus saving costs.

Here, “Business A Application 1” is called a “module” in Koupleless terminology. Multiple module applications can be merged into the same base using SOFAArk technology. The base can be a completely empty SpringBoot application (Java technology stack), or it can sink some common SDKs to the base. Each time a module application is deployed, it restarts the base machine. In this way, module applications maximize the reuse of the base’s memory (Metaspace and Heap), reduce the size of build artifacts from hundreds of MB to tens of MB or even more aggressively, and effectively improve CPU usage.

Pain Point 3: Low Collaboration Efficiency in Enterprise R&D

In enterprises, some applications require multi-person development collaboration. In the traditional development mode, each person’s code change requires the entire application to be released, leading to a fire-fighting approach to application development iteration. Everyone needs to develop iteratively within a unified time window and release online at a unified time, resulting in a large number of demand release waits, environment machine preemptions, iteration conflicts, and other situations.
By using Koupleless, you can easily split applications into a base and multiple functional modules, where each functional module is a group of code files. Different functional modules can be developed and deployed iteratively simultaneously, and they are independent of each other, eliminating the traditional application iteration fire-fighting approach. Each module has its independent iteration, greatly improving the efficiency of demand delivery. If you enable hot deployment for modules (or restart the entire base each time a module is deployed), the single build + deployment time for modules will also be reduced from 6-10 minutes of normal applications to seconds.

Pain Point 4: Difficulties in Accumulating Business Assets to Improve Middle Platform Efficiency

In some medium and large enterprises, various business middle platforms are accumulated. Middle platforms generally encapsulate the common API implementation and SPI definitions of the business. The SPI definition allows plugins on the middle platform to implement their own business logic. After the traffic enters the middle platform application, it calls the corresponding SPI implementation component to complete the corresponding business logic. Components in the middle platform application have relatively simple business logic. Deploying them as independent applications will incur high resource and operation costs and slow build and deployment speeds, significantly increasing the development burden and affecting development efficiency.
With Koupleless, you can easily split the middle platform application into a base and multiple functional modules. The base can accumulate relatively thick business dependencies, common logic, API implementations, SPI definitions, etc. (referred to as business assets), and provide them to the modules above. The modules can use the capabilities of the base through direct calls between objects or beans, with almost no code modification. Moreover, multiple modules can be developed and deployed iteratively simultaneously without affecting each other, greatly improving collaborative delivery efficiency. Additionally, for relatively simple modules, you can also enable hot deployment, and the single build + deployment time will be reduced from 6-10 minutes of normal applications to within 30 seconds.

Pain Point 5: High Cost of Microservice Evolution

Different businesses in enterprises have different development stages, so applications also have their own lifecycles.

Startup Phase: A startup application generally adopts a monolithic architecture.
↓
Growth Phase: As the business grows, the number of application developers also increases. At this time, you may be uncertain about the future prospects of the business and do not want to split the business into multiple applications prematurely to avoid unnecessary maintenance, governance, and resource costs. Therefore, you can use Koupleless to cost-effectively split the application into a base and multiple functional modules, allowing different functional modules to be developed, operated, and iterated independently in parallel, thus improving the collaboration and demand delivery efficiency of the application in this stage.
↓
Mature Phase: As the business further expands, you can use Koupleless to cost-effectively split some or all functional modules into independent applications for development and operation.
↓
Long-tail Phase: Some businesses may gradually enter a low-activity or long-tail phase after experiencing growth or maturity phases. At this time, you can use Koupleless to easily convert these applications into modules, merge them, and deploy them together to achieve cost reduction and efficiency improvement.

It can be seen that Koupleless supports enterprises to smoothly transition between the startup, growth, mature, and long-tail phases of applications at a low cost and even switch back and forth, thereby easily keeping the application architecture synchronized with business development.
Application lifecycle evolution.

1.2 - 1.2 Industry Background

Issues with Microservices

As application architectures evolved from monolithic to microservices, combined with the development of software engineering from waterfall models to the current DevOps model, various problems such as scalability, distribution, and collaborative work have been addressed, providing enterprises with better agility and execution efficiency, bringing significant value. However, despite solving some problems, the microservices model has gradually exposed some issues that are currently receiving continuous attention:

Complex Infrastructure

High Cognitive Load

To fulfill a business requirement, there are actually many dependencies, components, and platforms providing various capabilities behind the scenes. If any component below the business layer encounters an exception that is perceived by the business, it will impose a significant cognitive burden and corresponding time cost on the business development personnel.

Various types of exceptions.

Heavy Operations Burden

The dependencies included in the business application also undergo continuous iterative upgrades, such as frameworks, middleware, various SDKs, etc. When encountering situations such as:

1. Major feature releases
2. Urgent bug fixes
3. Encountering significant security vulnerabilities

These dependencies’ new versions need to be upgraded as quickly as possible by the business. This leads to two problems:

For Business Development Personnel

If these dependency upgrades occur only once or twice, it’s not a problem. However, a business application relies on many frameworks, middleware, and various SDKs, and each dependency upgrade requires the involvement of business developers. Managing so many dependencies becomes a significant operational burden for business development personnel in the long term. Additionally, it’s important to note that the business’s common layer also imposes a significant burden on business developers.

For Infrastructure Personnel

Similarly, like the developers of various dependencies, each release of such a new version requires the business applications using them to be upgraded as quickly as possible. However, business development personnel are more concerned with delivering business requirements, so pushing them to complete upgrades quickly is not very realistic, especially in enterprises with many developers.

Slow Startup

Each business application startup process involves many steps, resulting in long waiting times for functionality verification.

Low Release Efficiency

Due to the aforementioned issues of slow startup and numerous exceptions, the deployment process takes a long time, and encountering exceptions that cause delays requires recovery and handling. In addition to platform exceptions, the probability of machine exceptions increases with the increasing number of machines. For example, if the probability of a machine completing a release without any issues (without encountering exceptions) is 99.9%, meaning the success rate in one attempt is 99.9%, then for 100 machines, it becomes 90%, and for 1000 machines, it decreases to only 36.7%. Therefore, applications with many machines often encounter deployment delays, requiring developer intervention, leading to low efficiency.

High Collaboration and Resource Costs

Monolithic/Large Applications are too Big

Blockage in Multilateral Cooperation

As businesses continue to grow, applications become larger, mainly reflected in the increasing number of developers, resulting in blockages in multilateral cooperation.

Large Impact of Changes, High Risk

As businesses continue to grow, online traffic increases, and the number of machines grows. However, a single change can affect all code and machine traffic, resulting in a large impact and high risk from changes.

Too Many Small Applications

During the evolution of microservices, over time, due to factors such as excessive application splitting, some businesses shrinking, or organizational restructuring, there is a continuous accumulation of small or long-tail applications online, resulting in an increasing number of applications. For example, in the past three years, the number of applications at Ant Group has tripled.

High Resource Costs

These applications require several machines in each data center, but in reality, the traffic is not significant, and CPU usage is very low, resulting in resource waste.

High Long-Term Maintenance Costs

These applications also require personnel for maintenance tasks, such as upgrading SDKs and fixing security vulnerabilities, leading to high long-term maintenance costs.

Inevitability of the Problem

A microservices system is an ecosystem, and after several years of evolution within a company, according to the 28 Law, a few large applications occupy a significant portion of the traffic. It is inevitable that problems such as oversized large applications and too many small applications will arise. However, there is no defined standard for what constitutes a large application or how many small applications are too many. Therefore, the pain points experienced by developers due to these problems are subtle, and unless the pain reaches a certain threshold, it is difficult to attract the attention and action of the company’s management.

How to Properly Decompose Microservices

The proper decomposition of microservices has always been a challenging problem, as there are no clear standards. This is also why the issues of oversized large applications and too many small applications exist. The root cause behind these problems is the flexibility of business and organization and the high cost of microservice decomposition, which results in inconsistent agility between the two.

Misalignment between Microservices Decomposition and Business/Organizational Agility

Business development is flexible, and organizational structures are constantly adjusting. However, microservice decomposition requires machine resources and incurs long-term maintenance costs. The misalignment in agility between the two leads to problems such as under-decomposition or over-decomposition, resulting in oversized large applications and too many small applications. If these problems are not fundamentally addressed, microservices governance will continue to encounter issues, causing developers to remain stuck in a cycle of low efficiency and governance challenges.

Problems Faced by Enterprises of Different Sizes

Industry Attempts at Solutions

The industry has many good ideas and projects attempting to solve these problems, such as service meshes, runtime applications, platform engineering, Spring Modulith, and Google ServiceWeaver. These solutions have had some effect but also come with limitations:

1. From the perspective of business developers, only part of the infrastructure is shielded, and the business’s common parts are not shielded.
2. Only some of the problems are addressed.
3. High cost of retrofitting existing applications.

Koupleless is evolving as a development framework and platform capability to address these issues.

1.3 - 1.3 Architecture Introduction

1.3.1 - 1.3.1 Architecture Principles

Modular Application Architecture

To address these issues, we have performed both horizontal and vertical splits on applications. Firstly, the vertical split involves dividing the application into base and business layers, corresponding to two layers of organizational responsibilities. The base team, like traditional applications, is responsible for machine maintenance, common logic abstraction, business architecture governance, and providing runtime resources and environments for business. By separating concerns, all underlying infrastructure below the business layer is shielded, allowing the focus to remain on the business itself. Secondly, we horizontally partition the business into multiple modules, allowing independent parallel iteration among them without interference. Since modules exclude the base part, their build artifacts are lightweight, and their startup logic only encompasses the business itself, enabling rapid startup and providing sub-second verification capabilities, thus optimizing module development efficiency to the utmost extent.

Before the split, each developer may have perceived all the code and logic from the framework to middleware to business common parts to business itself. After the split, the collaboration within the team has changed, and developers are divided into two roles: base and module developers. Module developers are not concerned with resources and capacity but enjoy the ability to deploy and verify changes in seconds, focusing solely on business logic.

Here it’s crucial to understand how we perform these vertical and horizontal splits. The split is for isolation, and isolation is for independent iteration, stripping unnecessary dependencies. However, isolation alone, without sharing, is akin to merely relocating deployment positions, which may not yield desirable results. Thus, besides isolation, we also emphasize sharing capabilities. Therefore, it’s essential to focus on understanding the principles behind modular architecture in terms of isolation and sharing.

Module Definition

Before delving further, let’s clarify what modules are in this context. Modules are derived by subtracting the base part from the original application. This subtraction is achieved by setting the scope of dependencies in the module as provided.


A module can be defined by these three points:

1. A jar package generated by SpringBoot packaging
2. A module: a SpringContext + a ClassLoader
3. Hot deployment (no need to restart the process during upgrade)

Isolation and Sharing of Modules

Modules are isolated in terms of configuration and code through ClassLoader and SpringContext. They share configurations and code classes between modules and bases through SOFAArk and between multiple modules through SpringContext Manager.

Within the JVM, this is achieved through:

1. Ark Container providing a multi-ClassLoader runtime environment
2. Arklet managing module lifecycles
3. Framework Adapter associating SpringBoot lifecycle with module lifecycle
4. SOFAArk’s default delegation loading mechanism bridging module and base class delegation loading
5. SpringContext Manager providing bean and service discovery mechanisms
6. Bases essentially being modules with independent SpringContext and ClassLoader

However, modularization technologies in the Java domain have developed for 20 years. Why can modularization technologies be scaled within Ant Group? The core reason lies in the multi-module capabilities based on SOFAArk and SpringContext Manager, which provide a low-cost usage approach.

Isolation Aspect

Compared to other modularization technologies, from an isolation perspective, JPMS and Spring Modulith impose limitations through custom rules, with Spring Modulith requiring verification in unit tests. The isolation capabilities are relatively weak and somewhat tricky, with significant retrofitting costs for legacy applications, and even infeasible for legacy applications. Similar to OSGi, SOFAArk employs ClassLoader and SpringContext for configuration and code, as well as bean and service isolation, maintaining consistency with the native application startup mode.

Sharing Aspect

While SOFAArk shares isolation mechanisms with OSGi, OSGi, JPMS, and Spring Modulith all require defining import/export lists or other configurations between source and target modules, resulting in high usage costs for business modules that need to understand and perceive multi-module technologies. SOFAArk defines a default class delegation loading mechanism and cross-module bean and service discovery mechanisms, enabling business usage of multi-module capabilities without modification.
Additionally, why can the modularization technology based on SOFAArk provide these default capabilities at low cost and emphasize low-cost usage? The main reason is that we have differentiated roles for modules, distinguishing between bases and modules. Based on this core reason, we have also attached importance to low-cost usage and made important design considerations and trade-offs. For specific design considerations and trade-offs, refer to the technical implementation article.

Inter-Module Communication

Inter-module communication relies primarily on the bean and service discovery mechanism provided by SpringContext Manager.

Module Evolution

Looking back at the mentioned major issues, it can be seen that through the isolation and sharing capabilities of modular architecture, problems such as complex infrastructure, collaboration blocking, and high resources and long-term maintenance costs can be solved. However, the issue of inconsistent agility between microservices splitting and business remains unresolved.

Here, we address this by reducing the cost of microservices splitting. So how do we reduce the cost of microservices splitting? The main approach is to introduce modular architecture between monolithic and microservices architectures.

1. Modules do not occupy resources, so splitting incurs no resource costs.
2. Modules do not include business common parts, frameworks, or middleware parts, so modules incur no long-term SDK upgrade and maintenance costs.
3. Modules themselves are SpringBoot, and we provide tools to assist in the low-cost splitting of monolithic applications into modular applications.
4. Modules have flexible deployment capabilities; they can be deployed together in one JVM or separately, allowing modules to evolve into microservices or revert to monolithic application modes at low cost.

The arrows in the diagram are bidirectional. If there are too many microservices currently split, multiple microservices can also be cost-effectively transformed into modules and deployed together in one JVM. So, the essence here is to add a bidirectional transitional modular architecture between monolithic and microservices architectures, reducing the cost of transformation while allowing developers to evolve or roll back according to business needs. This can solve several problems of microservices.

Advantages of Modular Architecture

The main advantages of modular architecture are concentrated in these four points: speed, savings, flexible deployment, and evolvability,

When compared to traditional applications, the data below show more than a 10x improvement in development, deployment, and runtime stages.

Platform Architecture

Just having application architecture is not enough. It is necessary to provide complete supporting capabilities from the development stage to the operation and runtime stages to truly realize the advantages of modular application architecture to developers.

During the development stage, it is necessary to provide capabilities for base access, module creation, and more importantly, local rapid build and debugging capabilities for modules; during the operation stage, provide fast module deployment capabilities, and on top of module deployment, provide A/B testing and second-level scaling capabilities; during the runtime stage, provide reliability capabilities for modules, fine-grained control of observability, traffic, scheduling, and scaling.

Component View

Within the entire platform, four components are needed:

1. Development tool Arkctl, providing module creation, rapid debugging testing, and other capabilities.
2. Runtime components SOFAArk, Arklet, providing module operation, module lifecycle management, and multi-module runtime environment.
3. Control plane components ModuleController
   1. ModuleDeployment provides module deployment and operation capabilities.
   2. ModuleScheduler provides module scheduling capabilities.
   3. ModuleScaler provides module scaling capabilities.

2 - 2. Quick Start

This quick start guide mainly introduces the dynamic merge deployment model, which is used to save resources and improve R&D efficiency. If you only want to save resources, you can use static merge deployment. This guide includes:

1. Base Access
2. Module Access
3. Module Development Verification
4. Module Deployment (not available yet, updates pending)

Video tutorials are also available, click here to view.

Prerequisites

Development Tools

• JDK 8, JDK 17, JDK 21+
• Maven v3.9.0+
• arkctl v0.2.1+, installation instructions can be found here

Operation and Maintenance Tools (not required for static merge deployment)

• Docker
• Kubectl
• K8s Cluster such as minikube v1.10+

Base Access

Refer to this link

Module Access

Refer to this link

Local Environment Development Verification

Check here

Module Deployment Example with Minikube Cluster (not available yet, updates pending)

Step 1: Deploy Operation and Maintenance Component ModuleController

kubectl apply -f xxx/xxx.yaml  

Step 2: Publish Using Sample Base

1. Deploy the base to the K8s cluster, create a service for the base, exposing the port,
   you can reference here
2. Execute minikube service base-web-single-host-service to access the base service

Step 3: Release the Module

There are two ways to release a module:

1. Directly deploy the local module jar package to the K8s cluster

arkctl deploy ${path to the jar package} --pod ${namespace}/${podname}  

2. Deploy and release via K8s module deployment
   Create a module deployment and use kubectl apply to publish

kubectl apply -f xxx/xxxxx/xx.yaml  

Step 4: Test Verification

For More Experiments, Please View Sample Cases

Click here

2.1 - 2.2 Module Operations

This quick start guide mainly introduces Module operations based on Module Controller V2. It includes:

1. Environment Preparation
2. Module Controller V2 Deployment
3. Test Base Preparation
4. Module Deployment and Status Checking

Environment Preparation

K8S Environment Deployment

Module Controller V2 builds Module operation capabilities based on K8S, so a basic K8S environment is needed first.

Note: Module Controller currently only supports arm64 / amd64 environments.

If you already have a K8S cluster, skip this section.

For local testing, it is recommended to use Minikube to quickly set up K8S locally. Minikube is an open-source tool for local Kubernetes deployment, helping quickly deploy K8S components.

To install Minikube, first, install the Docker environment: Docker Official Website

After installing Docker and starting the Docker daemon, Minikube installation preparation is complete.

Refer to the official documentation for Minikube installation.

Module Controller V2 Deployment

Module Controller V2 can be deployed in two ways:

1. Local execution (requires go environment, not recommended)
2. Image deployment (recommended)

Next, we will use image deployment as an example.

First, prepare necessary RBAC configuration for Module Controller V2.

1. Download Service Account YAML
2. Download Cluster Role YAML
3. Download Cluster Role Binding YAML

Then apply the above three YAML files to set permissions and bindings for the service account.

Next, prepare the Pod Yaml for Module Controller deployment:

apiVersion: v1
kind: Pod
metadata:
  name: module-controller
  labels:
    app: module-controller
spec:
  serviceAccountName: virtual-kubelet # Service Account configured in the previous step
  containers:
    - name: module-controller
      image: serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/release/module-controller-v2:v2.1.2
      imagePullPolicy: Always
      resources:
        limits:
          cpu: "1000m"
          memory: "400Mi"
      ports:
        - name: httpTunnel
          containerPort: 7777
      env:
        - name: ENABLE_HTTP_TUNNEL
          value: "true"

Apply the above YAML to the K8S cluster, and wait for the Module Controller Pod to reach the Running state.

The Module operations capability is now set up. Next, prepare the test base and test Module.

Test Base Deployment

To facilitate onboarding, a Docker image of a test base is provided. First, download the Base Yaml:

apiVersion: v1
kind: Pod
metadata:
  name: base
  labels:
    app: base
spec:
  containers:
    - name: base
      image: serverless-registry.cn-shanghai.cr.aliyuncs.com/opensource/test/base-web:1.1.1 # Pre-packaged image
      imagePullPolicy: Always
      ports:
        - name: base
          containerPort: 8080
        - name: arklet
          containerPort: 1238
      env:
        - name: MODULE_CONTROLLER_ADDRESS
          value: {YOUR_MODULE_CONTROLLER_IP}

Replace {YOUR_MODULE_CONTROLLER_IP} with the actual Module Controller Pod IP in the YAML.

Apply the modified YAML to the K8S cluster and wait for the Base Pod to reach the Running state.

Once the base has started, verify its successful mapping to a VNode with:

kubectl get nodes

If a node named vnode.test-base.dev appears and is Ready, the base is successfully started and mapped.

The UUID above is generated at base startup and changes each restart.

Next, use port-forward to expose the base container’s service for verification, using the command:

kubectl port-forward base 8080:8080

Visit link to verify if it maps successfully.

Module Deployment and Status Checking

Module Deployment

First, verify the state before Module installation by visiting the base service: Module Test.

It should return an error page indicating the Module is not installed.

Next, deploy the Module using a Deployment. Apply the Module YAML to K8S for Module deployment. Here is an example for a single Module:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: biz1
  labels:
    virtual-kubelet.koupleless.io/component: module-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      module: biz1
  template:
    metadata:
      labels:
        module: biz1
        virtual-kubelet.koupleless.io/component: module
    spec:
      containers:
        - name: biz1
          image: https://serverless-opensource.oss-cn-shanghai.aliyuncs.com/module-packages/stable/biz1-web-single-host-0.0.1-SNAPSHOT-ark-biz.jar
          env:
            - name: BIZ_VERSION
              value: 0.0.1-SNAPSHOT
      affinity:
        nodeAffinity:
          requiredDuringSchedulingIgnoredDuringExecution:
            nodeSelectorTerms:
              - matchExpressions:
                  - key: base.koupleless.io/version
                    operator: In
                    values:
                      - 1.0.0
                  - key: base.koupleless.io/name
                    operator: In
                    values:
                      - koupleless-sample
      tolerations:
        - key: "schedule.koupleless.io/virtual-node"
          operator: "Equal"
          value: "True"
          effect: "NoExecute"
        - key: "schedule.koupleless.io/node-env"
          operator: "Equal"
          value: "dev"
          effect: "NoExecute"

Once deployment is complete, use kubectl get pods to check the status of all Module pods.

When the pods created by the deployment reach the Running state, the Module installation is complete. Verify by visiting the base service again: Module Test.

You should see the content: hello to /biz1 deploy, indicating the Module installation is complete.

Module Deletion

Modules can be removed by deleting their Deployment with:

kubectl delete deployment biz1

Check the pod deletion success with kubectl get pods.

After deletion, visit the base service Module Test to verify Module uninstallation.

The page should revert to the state indicating the Module is uninstalled.

3 - 3. Video Tutorials

Koupleless (SOFAServerless) Module Local Development and Deployment Video Tutorial

Quick Tip: Only takes two minutes

For detailed written instructions, please click here experiment one

Koupleless (SOFAServerless) Platform and Development Framework Full Video Tutorial

This learning course is interactive and equipped with a complete sandbox environment for hands-on learning. Feel free to give it a try!

Step 1: Click here to register for an Open Source College account.

Step 2: After registration, if the page does not change, you will be directed to the “SofaServerless Interactive Lab” homepage. Then, choose the following course:

Click on “SOFAServerless Development Framework and Product Introduction” and then click “Start Learning”.

4 - 4. User Manual

4.1 - 4.1 Base Access

4.1.1 - 4.1.1 SpringBoot or SOFABoot Upgrade to Base

We can create Biz Module in three ways, and this article introduces the second one:

1. Splitting a large application into multiple modules
2. Transforming an existing application into a single module
3. Directly creating a module using a scaffold
4. Transform ordinary code fragments into a module

This article introduces the operation and verification steps of how to upgrade existing SpringBoot or SOFABoot to modules at a low cost. It only requires adding an ark packaging plugin and configuring module slimming to achieve the one-click upgrade of a regular application to a module application. With the same set of code branches, the application can be independently started like the original SpringBoot, and can also be merged and deployed together with other applications as a module.

Prerequisites

1. SpringBoot version >= 2.1.9.RELEASE (for SpringBoot users)
2. SOFABoot version >= 3.9.0 or SOFABoot >= 4.0.0 (for SOFABoot users)
3. Install maven version >= 3.9.0 locally

Note: SpringBoot version == 2.1.9.RELEASE, see Upgrade SpringBoot 2.1.9 to base

Access Steps

Code and Configuration Modifications

Modify application.properties

# Need to define the application name
spring.application.name = ${Replace with actual base app name}

Modify the main pom.xml

<properties>
    <sofa.ark.version>2.2.16</sofa.ark.version>
    <koupleless.runtime.version>1.3.3</koupleless.runtime.version>
</properties>

<!-- Place this as the first dependency in your build pom -->
<dependency>
    <groupId>com.alipay.koupleless</groupId>
    <artifactId>koupleless-base-starter</artifactId>
    <version>${koupleless.runtime.version}</version>
</dependency>

<!-- If using Spring Boot web, add this dependency. For more details, see https://www.sofastack.tech/projects/sofa-boot/sofa-ark-multi-web-component-deploy/ -->
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>web-ark-plugin</artifactId>
</dependency>

<!-- 为了让三方依赖和 koupleless 模式适配，需要引入以下构建插件 -->
<build>
    <plugins>
        <plugin>
            <groupId>com.alipay.sofa.koupleless</groupId>
            <artifactId>koupleless-base-build-plugin</artifactId>
            <version>${koupleless.runtime.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>add-patch</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Integration for Other Versions

Upgrade SpringBoot 2.1.9 to Base

After modifying the above configurations, additional modifications are required:

Modify main pom.xml

<!-- Place this as the first dependency in your pom -->
<dependency>
    <groupId>com.alipay.sofa.koupleless</groupId>
    <artifactId>koupleless-base-starter</artifactId>
    <version>${koupleless.runtime.version}</version>
</dependency>

<!-- If using Spring Boot web, add this dependency. For more details, see https://www.sofastack.tech/projects/sofa-boot/sofa-ark-multi-web-component-deploy/ -->
<dependency>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>web-ark-plugin</artifactId>
</dependency>
<dependency>
    <groupId>com.github.oshi</groupId>
    <artifactId>oshi-core</artifactId>
    <version>3.9.1</version>
</dependency>

        
<!-- 为了让三方依赖和 koupleless 模式适配，需要引入以下构建插件 -->
<build>
    <plugins>
        <plugin>
            <groupId>com.alipay.sofa.koupleless</groupId>
            <artifactId>koupleless-base-build-plugin</artifactId>
            <version>${koupleless.runtime.version}</version>
            <executions>
                <execution>
                    <goals>
                        <goal>add-patch</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

Modify base startup class

If version of koupleless is equals 1.1.0 or higher than 1.1.0, no need to change。

If version of koupleless is lower than 1.1.0, exclude the HealthAutoConfiguration class in the @SpringBootApplication annotation of the base Springboot startup class, as shown below:

import com.alipay.sofa.koupleless.arklet.springboot.starter.health.HealthAutoConfiguration;
@SpringBootApplication(exclude = { HealthAutoConfiguration.class })
public class BaseApplication {
    public static void main(String[] args) {
        SpringApplication.run(BaseApplication.class, args);
    }
}

Startup Verification

If the foundation application can start normally, the validation is successful!

4.2 - 4.2 Module Access

4.2.1 - 4.2.1 Upgrade to Module from existing SpringBoot or SOFABoot

We can create Biz Module in three ways, and this article introduces the second one:

1. Splitting a large application into multiple modules
2. Transforming an existing application into a single module
3. Directly creating a module using a scaffold

This article introduces how existing SpringBoot or SOFABoot applications can be cost-effectively upgraded to modules with the operational and validation steps. It requires only the addition of an ark packaging plugin + configuration for module slimming to enable a conventional application to be upgraded to a module application at the push of a button. Moreover, the same set of code branches can be used for independent startup as before, just like a regular SpringBoot application, as well as being capable of being deployed together with other applications as a module.

Prerequisites

1. SpringBoot version >= 2.3.0 (for SpringBoot users)
2. SOFABoot >= 3.9.0 or SOFABoot >= 4.0.0 (for SOFABoot users)

Access Steps

Step 1: Modify application.properties

# Need to define the application name
spring.application.name = ${Replace with actual module app name}

Step 2: Add Dependencies and Packaging Plugins for the Module

Note： The order of defining the sofa-ark plugin must be before the springboot packaging plugin;

<!-- Dependencies required for the module, mainly for inter-module communication --> 
<dependencies>
    <dependency>
        <groupId>com.alipay.sofa.koupleless</groupId>
        <artifactId>koupleless-app-starter</artifactId>
        <scope>provided</scope>
    </dependency>
</dependencies>

<plugins>
<!-- Add the ark packaging plugin here -->
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-maven-plugin</artifactId>
        <version>{sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                    <goal>repackage</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <skipArkExecutable>true</skipArkExecutable>
            <outputDirectory>./target</outputDirectory>
            <bizName>${Replace with module name}</bizName>
            <webContextPath>${Module's custom web context path}</webContextPath>
            <declaredMode>true</declaredMode>
        </configuration>
    </plugin>
<!-- Build a regular SpringBoot fat jar, used for independent deployment, can be removed if not needed -->
    <plugin>
        <!-- Original spring-boot packaging plugin -->
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
    </plugin>
</plugins>

Step 3: Automate Module Slimming

You can leverage the automated slimming capability provided by the ark packaging plugin to slim down the Maven dependencies in your module application. This step is mandatory; otherwise, the resulting module JAR file will be very large, and startup may fail. Extended Reading: If the module does not optimize its dependenciesWhat will happen if SpringBoot framework is imported independently?

Step 4: Build the Module Jar Package

Execute mvn clean package -DskipTest, you can find the packaged ark biz jar in the target directory, or you can find the packaged regular springboot jar in the target/boot directory.

Tip：Full Middleware Compatibility List Supported in the Module。

Experiment: Verifying that the module can be started independently and deployed as a combined module

After adding the module packaging plugin (sofa-ark-maven-plugin) for packaging, only the ark-biz.jar build artifact will be added, which does not conflict with or affect the executable Jar built by the native spring-boot-maven-plugin. When deploying on the server, if you want to start independently, use the executable Jar built by the native spring-boot-maven-plugin as the build artifact; if you want to deploy as an ark module to the base, use the ark-biz.jar built by the sofa-ark-maven-plugin as the build artifact.

Verification of Deployment to the Base

1. Start the base from the previous step (verification of independent startup).
2. Initiate module deployment

curl --location --request POST 'localhost:1238/installBiz' \
--header 'Content-Type: application/json' \
--data '{
    "bizName": "${Module Name}",
    "bizVersion": "${Module Version}",
    "bizUrl": "file:///path/to/ark/biz/jar/target/xx-xxxx-ark-biz.jar"
}'

If the following information is returned, it indicates that the module is installed successfully.

3. View Current Module Information: Besides the base “base,” there is also a module named “dynamic-provider.”

4. Uninstall the module

curl --location --request POST 'localhost:1238/uninstallBiz' \
--header 'Content-Type: application/json' \
--data '{
    "bizName": "dynamic-provider",
    "bizVersion": "0.0.1-SNAPSHOT"
}'

If the following information is returned, it indicates that the uninstallation was successful.

{
    "code": "SUCCESS",
    "data": {
        "code": "SUCCESS",
        "message": "Uninstall biz: dynamic-provider:0.0.1-SNAPSHOT success."
    }
}

Verification of Independent Startup

After transforming a regular application into a module, it can still be started independently to verify some basic startup logic. Simply check the option to automatically add provided scope to the classpath in the startup configuration, and then use the same startup method as for regular applications. Modules transformed through automatic slimming can also be started directly using the SpringBoot jar package located in the target/boot directory. For more details, please refer to this link

4.2.2 - 4.2.2 Creating Modules Using Maven Archetype

We can create Biz Module in three ways, and this article introduces the second one:

1. Splitting a large application into multiple modules
2. Transforming an existing application into a single module
3. Directly creating a module using a scaffold
4. Transform ordinary code fragments into a module

It’s easy to creating a module from maven archetype, all you need to do is input the Maven groupId and artifactId for the archetype in IDEA.

<dependency>
    <groupId>com.alipay.sofa.koupleless</groupId>
    <artifactId>koupleless-common-module-archetype</artifactId>
    <version>{koupleless.runtime.version}</version>
</dependency>

The module created from this archetype has already integrated the module packaging plugin and automatic slimming configuration. It can be directly packaged as a module and installed on the base, or started independently locally.

4.2.3 -

title: 4.2.3 Java Code Fragment as Module
date: 2024-01-25T10:28:32+08:00
description: Java Code Fragment as Module
weight: 310

Module creation has four methods, and this article introduces the fourth method:

1. Split multiple modules from a large application
2. Transform existing applications into a single module
3. Create a module directly using scaffolding
4. Transform ordinary code fragments into a module

This article introduces the operation and verification steps of upgrading Java code fragments to modules, and only requires adding an ark packaging plugin and configuring module slimming to achieve the one-click upgrade of Java code fragments into module applications. It enables the same set of code branches to be independently started like the original Java code fragments, and can also be deployed and started with other applications as a module.

Prerequisites

• JDK 8
  • sofa.ark.version >= 2.2.14-SNAPSHOT
  • koupleless.runtime.version >= 1.3.1-SNAPSHOT
• JDK 17/JDK 21
  • sofa.ark.version >= 3.1.7-SNAPSHOT
  • koupleless.runtime.version >= 2.1.6-SNAPSHOT

Integration Steps

Step 1: Add dependencies and packaging plugins required for the module

<properties>
    <sofa.ark.version>${see-prerequisites-above}</sofa.ark.version>
    <!-- Use different koupleless versions for different JDK versions, see: https://koupleless.io/docs/tutorials/module-development/runtime-compatibility-list/#%E6%A1%86%E6%9E%B6%E8%87%AA%E8%BA%AB%E5%90%84%E7%89%88%E6%9C%AC%E5%85%BC%E5%AE%B9%E6%80%A7%E5%85%B3%E7%B3%BB -->
    <koupleless.runtime.version>${see-prerequisites-above}</koupleless.runtime.version>
</properties>

<dependencies>
    <dependency>
        <groupId>com.alipay.sofa.koupleless</groupId>
        <artifactId>koupleless-app-starter</artifactId>
        <version>${koupleless.runtime.version}</version>
        <scope>provided</scope>
    </dependency>
</dependencies>
<plugins>
    <!-- Add the ark packaging plugin here -->
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-maven-plugin</artifactId>
        <version>{sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                    <goal>repackage</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <skipArkExecutable>true</skipArkExecutable>
            <outputDirectory>./target</outputDirectory>
            <bizName>${replace-with-module-name}</bizName>
            <declaredMode>true</declaredMode>
        </configuration>
    </plugin>
    
    <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-jar-plugin</artifactId>
        <version>3.2.0</version>
        <executions>
            <execution>
                <goals>
                    <goal>jar</goal>
                </goals>
                <phase>package</phase>
                <configuration>
                    <classifier>lib</classifier>
                    <!-- Ensure other necessary configuration here -->
                </configuration>
            </execution>
        </executions>
    </plugin>
</plugins>

Step 2: Add initialization logic

Add MainApplication.init() in the code snippet to initialize the container.

public static void main(String[] args) {
        // Initialize the module's instance container
        MainApplication.init();
        // ...
    }

In terms of communication between modules and the base, the module registers instances in the container, and the base obtains module instances through SpringServiceFinder. Using biz3 as an example:

1. biz3 implements two instances that are based on the AppService interface: Biz3AppServiceImpl and Biz3OtherAppServiceImpl:

public class Biz3OtherAppServiceImpl implements AppService {
    // Get the base bean
    private AppService baseAppService = SpringServiceFinder.getBaseService(AppService.class);
    @Override
    public String getAppName() {
        return "biz3OtherAppServiceImpl in the base: " + baseAppService.getAppName();
    }
}
public class Biz3AppServiceImpl implements AppService {
  // Get the base bean
  private AppService baseAppService = SpringServiceFinder.getBaseService(AppService.class);
  public String getAppName() {
    return "biz3AppServiceImpl in the base: " + baseAppService.getAppName();
  }
}

In which, the module obtains the base bean using: SpringServiceFinder.getBaseService(XXX.class), details can be found in: Module and Base Communication under ‘Module calls the base approach two: programming API SpringServiceFinder’.

2. biz3 registers instances of these two classes in the container:

public static void main(String[] args) {
        // Initialize the module's instance container
        MainApplication.init();
        // Register instances in the module container
        MainApplication.register("biz3AppServiceImpl", new Biz3AppServiceImpl());
        MainApplication.register("biz3OtherAppServiceImpl", new Biz3OtherAppServiceImpl());
        }

3. The base obtains instances from biz3:

@RestController
public class SampleController {
    // Get specific instances from biz3 through annotation
    @AutowiredFromBiz(bizName = "biz3", bizVersion = "0.0.1-SNAPSHOT", name = "biz3AppServiceImpl")
    private AppService biz3AppServiceImpl;
    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String hello() {
        System.out.println(biz3AppServiceImpl.getAppName());
        // Get specific instances from biz3 through an API
        AppService biz3OtherAppServiceImpl = SpringServiceFinder.getModuleService("biz3", "0.0.1-SNAPSHOT",
                "biz3OtherAppServiceImpl", AppService.class);
        System.out.println(biz3OtherAppServiceImpl.getAppName());
        // Get all instances of AppService class from biz3 through an API
        Map<String, AppService> appServiceMap = SpringServiceFinder.listModuleServices("biz3",
                "0.0.1-SNAPSHOT", AppService.class);
        for (AppService appService : appServiceMap.values()) {
            System.out.println(appService.getAppName());
        }
        return "hello to ark master biz";
    }
}

Where SpringBoot / SOFABoot base can obtain module instances through the @AutowiredFromBiz annotation or SpringServiceFinder.getModuleService() programming API, details can be found in: Module and Base Communication under ‘Base calls module’.

Step 3: Automate module slimming

Typically, module dependencies for code fragments are relatively simple. You can set the scope of dependencies in the module that are consistent with the base to “provided”, or use the automated slimming capability of the ark packaging plugin to automatically slim down the maven dependencies in the module. This step is mandatory, otherwise the module jar package will be very large and will result in startup errors.

Step 4: Build the module into a jar package

Execute mvn clean package -DskipTest, and you can find the packaged ark biz jar in the target directory.

Experiment: Verify the module can be deployed and merged

1. Start the base from the previous step (verify independent start-up steps)
2. Initiate module deployment Refer to the sample module deployment of biz3: https://github.com/koupleless/samples/blob/main/springboot-samples/service/README-zh_CN.md

4.3 - 4.3 Module Development

4.3.1 - 4.3.1 Coding Standards

Basic Specifications

1. The list of middleware clients officially verified and compatible in Koupleless modules can be found here. Any middleware client can be used in the base.
   
   
2. If you need to use System.setProperties() and System.getProperties() in module without sharing with the base, please add MultiBizProperties.initSystem() in the main method of the base platform. For details, refer to samples.
3. If the module hot unload capability is used, you can use the following API to decorate ExecutorService (typical for various thread pools), Timer, and Thread objects declared in the module code. When the module is unloaded, the Koupleless Arklet client will attempt to automatically clean up the decorated ExecutorService, Timer, and Thread:
   
   • In the module code, decorate the ExecutorService that needs to be automatically cleaned up. The underlying code will call the shutdownNow and awaitTermination interfaces of the ExecutorService object, attempting to gracefully release threads (not guaranteed to release 100%, such as when threads are waiting). The specific usage is:

     ShutdownExecutorServicesOnUninstallEventHandler.manageExecutorService(myExecutorService);
     

     Where myExecutorService needs to be a subtype of ExecutorService. You can also configure com.alipay.koupleless.executor.cleanup.timeout.seconds in the module’s SpringBoot or SOFABoot properties file to specify the graceful waiting time for thread pool awaitTermination.
     
     
   • In the module code, decorate the Timer that needs to be automatically cleaned up. The underlying code will call the cancel method of the Timer object. The specific usage is:

     CancelTimersOnUninstallEventHandler.manageTimer(myTimer);
     

     
     
     
   • In the module code, decorate the Thread that needs to be automatically cleaned up. The underlying code will forcibly call the stop method of the Thread object. The specific usage is:

     ForceStopThreadsOnUninstallEventHandler.manageThread(myThread);
     

     Note: JDK does not recommend forcibly stopping threads, as it may cause unexpected problems such as forcibly releasing locks on threads. Unless you are sure that forcibly closing threads will not cause any related issues, use it with caution.
     
     
4. If the module hot unload capability is used and there are other resources or objects that need to be cleaned up, you can listen for the Spring ContextClosedEvent event and clean up the necessary resources and objects in the event handler function. You can also specify their destroy-method at the place where Beans are defined in Spring XML. When the module is unloaded, Spring will automatically execute the destroy-method.
   
   
5. When the base is started, all modules will be deployed. Therefore, when coding the base, make sure to be compatible with all modules, otherwise the base deployment will fail. If there are incompatible changes that cannot be bypassed (usually there will be many incompatible changes between the base and modules during the module splitting process), please refer to Incompatible Base and Module Upgrade。
   

Knowledge Points

Module Slimming (Important)
Module-to-Module and Module-to-Base Communication (Important)
Module Testing (Important)
Reuse Base Interceptors in Modules
Reuse Base Data Sources in Modules
Introduction to the Principle of Class Delegation Between Base and Modules Multiple Configurations for Modules

4.3.2 - 4.3.2 Module Slimming

Why Slimming?

Using the underlying SOFAArk framework, Koupleless achieves class isolation between modules and between modules and the base. When the module starts, it initializes various objects and prioritizes using the module’s class loader to load classes, resources, and JAR files from the FatJar build artifact. Classes that cannot be found will be delegated to the base’s class loader for retrieval.

Based on this class delegation loading mechanism, the common classes, resources, and JAR files shared by the base and modules all sink into the base, allowing the module build artifact to be very small, resulting in very low memory consumption for the module and very fast startup.

Furthermore, after the module starts, many objects will be created in the Spring context. If module hot-unloading is enabled, complete recycling may not be possible, and excessive installations can cause high overhead in the Old generation and Metaspace, triggering frequent FullGC. Therefore, it is necessary to control the size of individual module packages to be < 5MB. In this way, the base can hot deploy and hot unload hundreds of times without replacement or restarting.

The so-called “module slimming” means that the JAR dependencies already present in the base do not participate in the module packaging and construction, thus achieving the two benefits mentioned above:

• Increase the speed of module installation, reduce module package size, reduce startup dependencies, and control module installation time < 30 seconds, or even < 5 seconds.
• In the hot deploy and hot unload scenario, the base can hot deploy and hot unload hundreds of times without replacement or restart.

Slimming Principles

The principle of building the ark-biz jar package is to place common packages such as frameworks and middleware in the base as much as possible while ensuring the functionality of the module, and reuse the base packages in the module, making the resulting ark-biz jar more lightweight.

In different scenarios, complex applications can choose different slimming methods.

Scenarios and Corresponding Slimming Methods

Scenario 1: The base and the module have close cooperation, such as the middle platform mode/shared library mode

In the case of close cooperation between the base and modules, the modules should perceive some facade classes of the base and the dependency versions currently used by the base during development, and import the required dependencies as needed. During module packaging, only two types of dependencies should be included: dependencies that the base does not have, and dependencies whose versions are inconsistent with those of the base.

Therefore, the base needs to:

1. Unified control over module dependency versions to let module developers know which dependencies the base has during development, to mitigate risks, and allow module developers to import part of the dependencies as needed without specifying versions.

The module needs to:

1. Only include dependencies that are not in the base and dependencies whose versions are inconsistent with those of the base during packaging to reduce the cost of slimming the module

Step 1: Packaging “base-dependencies-starter”

Objective

This step will produce “base-dependencies-starter” for unified control of module dependency versions.

Pom configuration for base bootstrap:

Note: The dependencyArtifactId in the following configuration needs to be modified, generally to ${baseAppName}-dependencies-starter

<build>
<plugins>
    <plugin>
        <groupId>com.alipay.sofa.koupleless</groupId>
        <artifactId>koupleless-base-build-plugin</artifactId>
        <!--        koupleless.runtime.version >= 1.3.0 -->
        <version>${koupleless.runtime.version}</version>
        <configuration>
            <!-- Generate the artifactId of the starter (groupId consistent with the base), which needs to be modified here!! -->
            <dependencyArtifactId>${baseAppName}-dependencies-starter</dependencyArtifactId>
            <!-- Generate the version number of the jar -->
            <dependencyVersion>0.0.1-SNAPSHOT</dependencyVersion>
            <!-- For debugging, change to true to see the intermediate products of the packaging -->
            <cleanAfterPackageDependencies>false</cleanAfterPackageDependencies>
        </configuration>
    </plugin>
  </plugins>
</build>

Local test

1. Pack the base-dependencies-starter jar: execute the command in the root directory of the base:

mvn com.alipay.sofa.koupleless:koupleless-base-build-plugin::packageDependency -f ${Relative path of the base bootstrap pom to the root directory of the base} 

The constructed pom will be in the outputs directory and will be automatically installed in the local Maven repository.

Note, this step will not upload “base-dependencies-starter” to the maven repository. We welcome further discussion to supplement the solution of “uploading to the maven repository”.

Step 2: Module modification packaging plugin and parent

Objective

1. When developing the module, use the “base-dependencies-starter” from Step 1 as the parent of the module project for unified management of dependency versions;
2. Modify the module packaging plug-in to only include “dependencies not in the base” and “dependencies whose versions are inconsistent with those of the base” when packaging the module, eliminating the need to manually configure “provided” and achieving automatic slimming of the module.

In addition: For some dependencies, even if the module and base use the same dependency version, the dependency needs to be retained when the module is packaged, i.e., the module slimming dependency whitelist needs to be configured. This feature will be launched at the end of July.

Configure the parent in the module’s root directory pom:

<parent>
   <groupId>com.alipay</groupId>
   <artifactId>${baseAppName}-dependencies-starter</artifactId>
   <version>0.0.1-SNAPSHOT</version>
</parent>

Configure plugin in the module’s packaging pom:

<build>
   <plugins>
       <plugin>
           <groupId>com.alipay.sofa</groupId>
           <artifactId>sofa-ark-maven-plugin</artifactId>
           <!--           since ${sofa.ark.version} >= 2.2.13    -->
           <version>${sofa.ark.version}</version>
           <executions>
               <execution>
                   <id>default-cli</id>
                   <goals>
                       <goal>repackage</goal>
                   </goals>
               </execution>
           </executions>
           <configuration>
               <!-- Configure the identifier of "base-dependencies-starter", standardized as '${groupId}:${artifactId}':'version' -->
               <baseDependencyParentIdentity>com.alipay:${baseAppName}-dependencies-starter:0.0.1-SNAPSHOT</baseDependencyParentIdentity>
           </configuration>
       </plugin>
   </plugins>
</build>

Step 3: Configure Module Dependency Whitelist

For some dependencies, even if the module and base use the same version of the dependency, the dependency needs to be retained when the module is packaged. This requires configuring a module slimming dependency whitelist. This feature will be launched by the end of July.

Step 4: Package Building

Scenario 2: The base and the module have loose cooperation, such as resource saving in multi-application merge deployment

In the case of loose cooperation between the base and the module, the module should not perceive the dependency versions currently used by the base during development, so the module needs to focus more on the low-cost access to module slimming. Dependencies that need to be excluded from module packaging can be configured.

Method 1: SOFAArk Configuration File Combining

Step 1

SOFAArk Module Slimming reads configuration from two places:

• “Module Project Root Directory/conf/ark/bootstrap.properties”, such as: my-module/conf/ark/bootstrap.properties
• “Module Project Root Directory/conf/ark/bootstrap.yml”, such as: my-module/conf/ark/bootstrap.yml

Configuration

bootstrap.properties (recommended)

Configure the common package of frameworks and middleware that need to be sunk to the base in “Module Project Root Directory/conf/ark/bootstrap.properties” in the following format, such as:

# excludes config ${groupId}:{artifactId}:{version}, split by ','
excludes=org.apache.commons:commons-lang3,commons-beanutils:commons-beanutils
# excludeGroupIds config ${groupId}, split by ','
excludeGroupIds=org.springframework
# excludeArtifactIds config ${artifactId}, split by ','
excludeArtifactIds=sofa-ark-spi

bootstrap.yml (recommended)

Configure the common package of frameworks and middleware that need to be sunk to the base in “Module Project Root Directory/conf/ark/bootstrap.yml” in the following format, such as:

# excludes config ${groupId}:{artifactId}:{version}, split by '-'
# excludeGroupIds config ${groupId}, split by '-'
# excludeArtifactIds config ${artifactId}, split by '-'
excludes:
  - org.apache.commons:commons-lang3
  - commons-beanutils:commons-beanutils
excludeGroupIds:
  - org.springframework
excludeArtifactIds:
  - sofa-ark-spi

Step 2

Upgrade the module packaging plug-in sofa-ark-maven-plugin version >= 2.2.12

    <!-- Plugin 1: Packaging plug-in for sofa-ark biz to package as ark biz jar -->
    <plugin>
        <groupId>com.alipay.sofa</groupId>
        <artifactId>sofa-ark-maven-plugin</artifactId>
        <version>${sofa.ark.version}</version>
        <executions>
            <execution>
                <id>default-cli</id>
                <goals>
                    <goal>repackage</goal>
                </goals>
            </execution>
        </executions>
        <configuration>
            <skipArkExecutable>true</skipArkExecutable>
            <outputDirectory>./target</outputDirectory>
            <bizName>biz1</bizName>
            <webContextPath>biz1</webContextPath>
            <declaredMode>true</declaredMode>
        </configuration>
    </plugin>

Step 3

Simply build the module ark-biz jar package, and you will see a significant difference in the size of the slimmed ark-biz jar package.

You can click here to view the complete example project for module slimming.

4.3.3 - 4.3.3 Module Startup

Module Startup Parameters

Modules can be deployed in two ways: static merged deployment and hot deployment.
Static merged deployment does not support configuration startup parameters. Most of the startup parameters for the module can be placed in the module configuration (application.properties); for example, when configuring the profile: change the startup parameter --spring.profiles.active=dev to spring.profiles.active=true in the application.properties file.
Hot deployment modules support configuration of startup parameters. For example, when using Arklet to install a module via a web request, you can configure startup parameters and environment variables:

curl --location --request POST 'localhost:1238/installBiz' \
--header 'Content-Type: application/json' \
--data '{
    "bizName": "${Module Name}",
    "bizVersion": "${Module Version}",
    "bizUrl": "file:///path/to/ark/biz/jar/target/xx-xxxx-ark-biz.jar",
    "args": ["--spring.profiles.active=dev"],
    "env": {
        "XXX": "YYY"
    }
}'

Module Startup Acceleration

Design Concept for Module Startup Acceleration

The overall idea for module startup acceleration is:

1. The base platform should start the services in advance, which only requires the base platform to pre-import the dependencies.
2. The module can reuse the base platform’s services in various ways. The methods for reusing the base services include, but are not limited to, analyzing the specific use case; if there are any questions, feel free to discuss in the community group:
   1. Reuse through sharing class static variables.
   2. Reuse by having the base platform encapsulate some service interface APIs, allowing the module to call these APIs directly.
   3. Obtain proxy objects of base platform objects through annotations, using tools provided by Koupleless like @AutowiredFromBase, @AutowiredFromBiz, SpringServiceFinder, and some annotations supporting JVM service calls provided by Dubbo or SOFARpc.
   4. Find objects across modules to directly obtain base platform objects, using tools like SpringBeanFinder provided by Koupleless. There is an implicit issue here: for modules to successfully invoke base platform services, they need to use certain model classes. Therefore, modules typically need to import the dependencies corresponding to those services, leading to these service configurations being scanned during module startup, which may result in reinitializing these services. This can cause unnecessary services to start and slow down the module startup, increasing memory consumption. Thus, to accelerate module startup, three tasks must be completed:
3. The base platform should start the services in advance.
4. The module should prohibit the startup of these services, which is the focus of this article.
5. The module should reuse base platform services.

How Modules Can Prohibit Startup of Certain Services

Starting from version 1.1.0, Koupleless provides the following configuration capability:

koupleless.module.autoconfigure.exclude # Services that do not need to start during module startup
koupleless.module.autoconfigure.include # Services that need to start during module startup. If a service is configured with both include and exclude, the service will start.

This configuration can be set in the base platform or in the module. If configured in the base platform, it applies to all modules. If configured in the module, it only applies to that module and will override the configuration in the base platform.

Benchmark

Detailed benchmark information is yet to be added.

4.3.4 - 4.3.4 Module Communication Module to Module and Module to Base Communication

Between the base and modules, and among modules, there is spring context isolation, meaning their beans do not conflict and are not visible to each other. However, in many scenarios such as the middleware mode and independent module mode, there are situations where the base calls the module, the module calls the base, and modules call each other. Currently, three methods are supported for invocation: @AutowiredFromBiz, @AutowiredFromBase, and SpringServiceFinder method calls. Note that the usage of these three methods varies.

Spring Environment

Importing Dependencies in Modules

<dependency>
    <groupId>com.alipay.koupleless</groupId>
    <artifactId>koupleless-app-starter</artifactId>
    <version>0.5.6</version>
    <scope>provided</scope>
</dependency>

Base Calling Module

Only SpringServiceFinder can be used.

@RestController
public class SampleController {

    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String hello() {

        Provider studentProvider = SpringServiceFinder.getModuleService("biz", "0.0.1-SNAPSHOT",
                "studentProvider", Provider.class);
        Result result = studentProvider.provide(new Param());

        Provider teacherProvider = SpringServiceFinder.getModuleService("biz", "0.0.1-SNAPSHOT",
                "teacherProvider", Provider.class);
        Result result1 = teacherProvider.provide(new Param());
        
        Map<String, Provider> providerMap = SpringServiceFinder.listModuleServices("biz", "0.0.1-SNAPSHOT",
                Provider.class);
        for (String beanName : providerMap.keySet()) {
            Result result2 = providerMap.get(beanName).provide(new Param());
        }

        return "hello to ark master biz";
    }
}

Module Calling Base

Method 1: Annotation @AutowiredFromBase

@RestController
public class SampleController {

    @AutowiredFromBase(name = "sampleServiceImplNew")
    private SampleService sampleServiceImplNew;

    @AutowiredFromBase(name = "sampleServiceImpl")
    private SampleService sampleServiceImpl;

    @AutowiredFromBase
    private List<SampleService> sampleServiceList;

    @AutowiredFromBase
    private Map<String, SampleService> sampleServiceMap;

    @AutowiredFromBase
    private AppService appService;

    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String hello() {

        sampleServiceImplNew.service();

        sampleServiceImpl.service();

        for (SampleService sampleService : sampleServiceList) {
            sampleService.service();
        }

        for (String beanName : sampleServiceMap.keySet()) {
            sampleServiceMap.get(beanName).service();
        }

        appService.getAppName();

        return "hello to ark2 dynamic deploy";
    }
}

Method 2: Programming API SpringServiceFinder

@RestController
public class SampleController {

    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String hello() {

        SampleService sampleServiceImplFromFinder = SpringServiceFinder.getBaseService("sampleServiceImpl", SampleService.class);
        String result = sampleServiceImplFromFinder.service();
        System.out.println(result);

        Map<String, SampleService> sampleServiceMapFromFinder = SpringServiceFinder.listBaseServices(SampleService.class);
        for (String beanName : sampleServiceMapFromFinder.keySet()) {
            String result1 = sampleServiceMapFromFinder.get(beanName).service();
            System.out.println(result1);
        }

        return "hello to ark2 dynamic deploy";
    }
}

Module Calling Module

Referencing the module calling the base, the annotation is used with @AutowiredFromBiz and the programming API is supported by SpringServiceFinder.

Method 1: Annotation @AutowiredFromBiz

@RestController
public class SampleController {

    @AutowiredFromBiz(bizName = "biz", bizVersion = "0.0.1-SNAPSHOT", name = "studentProvider")
    private Provider studentProvider;

    @AutowiredFromBiz(bizName = "biz", name = "teacherProvider")
    private Provider teacherProvider;

    @AutowiredFromBiz(bizName = "biz", bizVersion = "0.0.1-SNAPSHOT")
    private List<Provider> providers;

    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String hello() {

        Result provide = studentProvider.provide(new Param());

        Result provide1 = teacherProvider.provide(new Param());

        for (Provider provider : providers) {
            Result provide2 = provider.provide(new Param());
        }

        return "hello to ark2 dynamic deploy";
    }
}

Method 2: Programming API SpringServiceFinder

@RestController
public class SampleController {

    @RequestMapping(value = "/", method = RequestMethod.GET)
    public String hello() {

        Provider teacherProvider1 = SpringServiceFinder.getModuleService("biz", "0.0.1-SNAPSHOT", "teacherProvider", Provider.class);
        Result result1 = teacherProvider1.provide(new Param());

        Map<String, Provider> providerMap = SpringServiceFinder.listModuleServices("biz", "0.0.1-SNAPSHOT", Provider.class);
        for (String beanName : providerMap.keySet()) {
            Result result2 = providerMap.get(beanName).provide(new Param());
        }

        return "hello to ark2 dynamic deploy";
    }
}

Complete Example

SOFABoot Environment

Please refer to this documentation

4.3.5 - 4.3.5 Module Local Development and Debugging

Arkctl Tool Installation

The Arkctl module installation mainly provides automated packaging and deployment capabilities, including invoking the mvn command to automatically build the module as a JAR file and calling the API interface provided by Arklet for completion of deployment. The installation method for Arkctl can refer to the documentation: arkctl Installation in the Local Environment Development Verification section.

Installation Method 1: Using the Golang Toolchain

1. Download the corresponding version of Golang from the Golang official website; the version must be above 1.21.
2. Execute the command go install github.com/koupleless/arkctl@v0.2.1 to install the Arkctl tool.

Installation Method 2: Downloading Binary Files

1. Download Arkctl based on the actual operating system. Download Arkctl.
2. Unzip the corresponding binary file and place it in a directory that is included in the system’s PATH variable.
3. After the base and module have been modified and the base has been started, the Arkctl tool can be used to quickly complete the build and deployment of the module into the base.
    

How to Find the PATH Value on Linux/Mac?

Execute in the terminal:

echo $PATH  
# Choose a directory and place arkctl in that directory  

How to Find the PATH Value on Windows?

Press Windows + R, type cmd, and then press Enter to open the command prompt. In the command prompt window, enter the following command and press Enter:

echo %PATH%  

Note: In the Windows environment, if Windows Defender is enabled, it may falsely report issues when downloading binaries through the browser, as shown below:

Local Quick Deployment

You can use the Arkctl tool to quickly build and deploy modules, improving the efficiency of local debugging and development.

Scenario 1: Building a Module JAR and Deploying to a Locally Running Base.

Preparation:

1. Start a base locally.
2. Open a module project repository.
   Execute the command:

# This needs to be executed in the root directory of the repository.  
# For example, if it is a Maven project, execute it in the directory where the root pom.xml is located.  
arkctl deploy  

Once the command completes, it is successfully deployed, and the user can debug and validate the relevant module functionalities.

Scenario 2: Deploying a Locally Built JAR to a Locally Running Base.

Preparation:

1. Start a base locally.
2. Prepare a built JAR file.
   Execute the command:

arkctl deploy /path/to/your/pre/built/bundle-biz.jar  

Once the command completes, it is successfully deployed, and the user can debug and validate the relevant module functionalities.

Scenario 3: Deploying a Locally Unbuilt JAR to a Locally Running Base.

Preparation:

1. Start a base locally.
   Execute the command:

arkctl deploy ./path/to/your/biz/  

Note: This command is applicable if the module can be built independently (e.g., if commands like mvn package can be successfully executed in the biz directory), the command will automatically build the module and deploy it to the base.

Scenario 4: Building and Deploying Submodule JARs in a Multi-Module Maven Project from the Root.

Preparation:

1. Start a base locally.
2. Open a multi-module Maven project repository.
   Execute the command:

# This needs to be executed in the root directory of the repository.  
# For example, if it is a Maven project, execute it in the directory where the root pom.xml is located.  
arkctl deploy --sub ./path/to/your/sub/module  

Once the command completes, it is successfully deployed, and the user can debug and validate the relevant module functionalities.

Scenario 5: Building a Module JAR and Deploying to a Remote Running K8s Base.

Preparation:

1. Ensure that a base pod is already running remotely.
2. Open a module project repository.
3. You must have a K8s certificate with exec permissions and the kubectl command-line tool available locally.
   Execute the command:

# This needs to be executed in the root directory of the repository.  
# For example, if it is a Maven project, execute it in the directory where the root pom.xml is located.  
arkctl deploy --pod {namespace}/{podName}  

Once the command completes, it is successfully deployed, and the user can debug and validate the relevant module functionalities.

Scenario 6: How to Use This Command More Quickly

You can create a Shell Script in IDEA, set the running directory, and then enter the corresponding Arkctl command as shown in the image below.

Local Module Debugging

Module and Base in the Same IDEA Project

Since the IDEA project can see the module code, debugging the module is no different from normal debugging. Just set breakpoints in the module code and start the base in debug mode.

Module and Base in Different IDEA Projects

1. Add the debug configuration to the base startup parameters: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000, then start the base.
2. Add remote JVM debug to the module, setting host to localhost: -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=8000.
3. Set breakpoints in the module.
4. After installing the module, you can begin debugging.

Checking Deployment Status

Scenario 1: Querying Modules Already Deployed in the Current Base.

Preparation:

1. Start a base locally.
   Execute the command:

arkctl status  

Scenario 2: Querying Modules Already Deployed in the Remote K8s Environment Base.

Preparation:

1. Start a base in the remote K8s environment.
2. Ensure you have Kube certificates and the necessary permissions locally.
   Execute the command:

arkctl status --pod {namespace}/{name}  

Viewing Runtime Module Status and Information Using Arthas

Retrieve All Biz Information

vmtool -x 1 --action getInstances --className com.alipay.sofa.ark.container.model.BizModel --limit 100  

For example:

Retrieve Specific Biz Information

# Please replace ${bizName}  
vmtool -x 1 --action getInstances --className com.alipay.sofa.ark.container.model.BizModel --limit 100 | grep ${bizName} -A 4  

For example:

Retrieve Biz Information Corresponding to a Specific BizClassLoader

# Please replace ${BizClassLoaderHashCode}  
vmtool -x 1 --action getInstances --className com.alipay.sofa.ark.container.model.BizModel --limit 100 | grep ${BizClassLoaderHashCode} -B 1 -A 3  

For example:

4.3.6 - 4.3.6 Reusing Base Data Source

Recommendation

It is highly recommended to use the approach outlined in this document to reuse the base data source within the module whenever possible. Failing to do so may result in repeated creation and consumption of data source connections during module deployments, leading to slower module publishing and operations, as well as increased memory usage.

SpringBoot Solution

Simply create a MybatisConfig class in the module’s code. This way, the transaction template is reused from the base, and only the Mybatis SqlSessionFactoryBean needs to be newly created. Refer to the demo: /koupleless/samples/springboot-samples/db/mybatis/biz1

Use SpringBeanFinder.getBaseBean to obtain the base Bean object, and then register it as the module’s Bean:

@Configuration
@MapperScan(basePackages = "com.alipay.sofa.biz1.mapper", sqlSessionFactoryRef = "mysqlSqlFactory")
@EnableTransactionManagement
public class MybatisConfig {

    // Note: Do not initialize a base DataSource, as it will be destroyed when the module is uninstalled. 
    // However, resources such as transactionManager, transactionTemplate, and mysqlSqlFactory can be safely destroyed.

    @Bean(name = "transactionManager")
    public PlatformTransactionManager platformTransactionManager() {
        return (PlatformTransactionManager) getBaseBean("transactionManager");
    }

    @Bean(name = "transactionTemplate")
    public TransactionTemplate transactionTemplate() {
        return (TransactionTemplate) getBaseBean("transactionTemplate");
    }

    @Bean(name = "mysqlSqlFactory")
    public SqlSessionFactoryBean mysqlSqlFactory() throws IOException {
        // The data source cannot be declared as a bean in the module's Spring context, as it will be closed when the module is uninstalled.

        DataSource dataSource = (DataSource) getBaseBean("dataSource");
        SqlSessionFactoryBean mysqlSqlFactory = new SqlSessionFactoryBean();
        mysqlSqlFactory.setDataSource(dataSource);
        mysqlSqlFactory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mappers/*.xml"));
        return mysqlSqlFactory;
    }
}

SOFABoot Solution

If the SOFABoot base does not enable multi-bundle (there is no MANIFEST.MF file in the Package), the solution is identical to the SpringBoot solution mentioned above. If there is a MANIFEST.MF file, you need to call BaseAppUtils.getBeanOfBundle to obtain the base Bean, where BASE_DAL_BUNDLE_NAME is theModule-Name in the MANIFEST.MF file:

@Configuration
@MapperScan(basePackages = "com.alipay.koupleless.dal.dao", sqlSessionFactoryRef = "mysqlSqlFactory")
@EnableTransactionManagement
public class MybatisConfig {

    // Note: Do not initialize a base DataSource, as it will be destroyed when the module is uninstalled. 
    // However, resources such as transactionManager, transactionTemplate, and mysqlSqlFactory can be safely destroyed

    private static final String BASE_DAL_BUNDLE_NAME = "com.alipay.koupleless.dal"

    @Bean(name = "transactionManager")
    public PlatformTransactionManager platformTransactionManager() {
        return (PlatformTransactionManager) BaseAppUtils.getBeanOfBundle("transactionManager",BASE_DAL_BUNDLE_NAME);
    }

    @Bean(name = "transactionTemplate")
    public TransactionTemplate transactionTemplate() {
        return (TransactionTemplate) BaseAppUtils.getBeanOfBundle("transactionTemplate",BASE_DAL_BUNDLE_NAME);
    }

    @Bean(name = "mysqlSqlFactory")
    public SqlSessionFactoryBean mysqlSqlFactory() throws IOException {
        // The data source cannot be declared as a bean in the module's Spring context, as it will be closed when the module is uninstalled.
        ZdalDataSource dataSource = (ZdalDataSource) BaseAppUtils.getBeanOfBundle("dataSource",BASE_DAL_BUNDLE_NAME);
        SqlSessionFactoryBean mysqlSqlFactory = new SqlSessionFactoryBean();
        mysqlSqlFactory.setDataSource(dataSource);
        mysqlSqlFactory.setMapperLocations(new PathMatchingResourcePatternResolver()
                .getResources("classpath:mapper/*.xml"));
        return mysqlSqlFactory;
    }
}

4.3.7 - 4.3.7 Reusing Base Interceptors

Objective

In the base, many Aspect interceptors (Spring interceptors) are defined, and you may want to reuse them in the module. However, the Spring contexts of the module and the base are isolated, which means that Aspect interceptors will not take effect in the module.

Solution

Create a proxy object for the original interceptor class, allowing the module to invoke this proxy object. Then, the module initializes this proxy object through the AutoConfiguration annotation. The complete steps and example code are as follows:

Step 1:

The base code defines an interface that defines the execution method of the interceptor. This interface needs to be visible to the module (referenced in the module dependencies):

public interface AnnotionService {
    Object doAround(ProceedingJoinPoint joinPoint) throws Throwable;
}

Step 2:

Write the specific implementation of the interceptor in the base. This implementation class needs to be annotated with @SofaService (SOFABoot) or @SpringService (SpringBoot, under construction):

@Service
@SofaService(uniqueId = "facadeAroundHandler")
public class FacadeAroundHandler implements AnnotionService {

    private final static Logger LOG = LoggerConst.MY_LOGGER;

    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        log.info("Start execution")
        joinPoint.proceed();
        log.info("Execution completed")
    }
}

Step 3:

In the module, use the @Aspect annotation to implement an Aspect. SOFABoot injects the FacadeAroundHandler on the base via @SofaReference. If it is SpringBoot, then use @AutowiredFromBase to inject FacadeAroundHandler on the base.

Note: Do not declare this as a bean, do not add @Component or @Service annotation, only @Aspect annotation is needed.

// Note: Do not declare this as a bean, do not add @Component or @Service annotation
@Aspect
public class FacadeAroundAspect {

    // If it is SOFABoot, use @SofaReference; if it is SpringBoot, use @AutowiredFromBase.
    @SofaReference(uniqueId = "facadeAroundHandler")
    //@AutowiredFromBase
    private AnnotionService facadeAroundHandler;

    @Pointcut("@annotation(com.alipay.linglongmng.presentation.mvc.interceptor.FacadeAround)")
    public void facadeAroundPointcut() {
    }

    @Around("facadeAroundPointcut()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        return facadeAroundHandler.doAround(joinPoint);
    }
}

Step 4:

Use the @Configuration annotation to create a Configuration class, and declare the aspectj objects needed by the module as Spring Beans.
Note: This Configuration class needs to be visible to the module, and related Spring Jar dependencies need to be imported with provided.

@Configuration
public class MngAspectConfiguration {
    @Bean
    public FacadeAroundAspect facadeAroundAspect() {
        return new FacadeAroundAspect();
    }
    @Bean
    public EnvRouteAspect envRouteAspect() {
        return new EnvRouteAspect();
    }
    @Bean
    public FacadeAroundAspect facadeAroundAspect() {
        return new FacadeAroundAspect();
    }
    
}

Step 5:

Explicitly depend on the Configuration class MngAspectConfiguration created in step 4 in the module code.

@SpringBootApplication
@ImportResource("classpath*:META-INF/spring/*.xml")
@ImportAutoConfiguration(value = {MngAspectConfiguration.class})
public class ModuleBootstrapApplication {
    public static void main(String[] args) {
        SpringApplicationBuilder builder = new SpringApplicationBuilder(ModuleBootstrapApplication.class)
        	.web(WebApplicationType.NONE);
        builder.build().run(args);
    }
}

4.3.8 - 4.3.8 Thread Pool Usage

Background

When multiple modules or a module and a base share the same thread pool, the Classloader used by the thread executing a task in the thread pool may differ from the Classloader that was used when the task was created. This can lead to a ClassNotFoundException when the thread pool executes the task.

As a result, when multiple modules or a module and a base share the same thread pool, in order to ensure consistency between the Classloader used during task execution and the Classloader used at the creation of the task, we need to make some modifications to the thread pool.

⚠️Note: There will be no such issue if each module uses its own thread pool.

There are 4 common ways to use thread pools in Java:

1. Directly create thread tasks and submit them to the thread pool, such as: Runnable, Callable, ForkJoinTask
2. Customize ThreadPoolExecutor and submit tasks to ThreadPoolExecutor
3. Use ThreadPoolExecutor or ScheduledThreadPoolExecutor from the third-party libraries.
4. Create thread pools through Executors and submit tasks to ExecutorService, ScheduledExecutorService, ForkJoinPool
5. For SpringBoot users, submit tasks to ThreadPoolTaskExecutor, SchedulerThreadPoolTaskExecutor

This article will introduce how each method is used on Koupleless.

How to Use

1. Directly create thread tasks and submit them to the thread pool

The original method:

threadPool.execute(new Runnable(){
    public void run() {
        //do something
    }
});


threadPool.execute(new Callable<String>(){
public String call() {
        //do something
        return "mock";
 }
});

If the threadPool remains unchanged, then it is necessary to wrap Runnable as KouplelessRunnable and Callable as KouplelessCallable, as follows:

// Runnable
// wrap function:
threadPool.execute(KouplelessRunnable.wrap(new Runnable(){
    public void run() {
        //do something
    }
});

// or new KouplelessRunnable:
threadPool.execute(new KouplelessRunnable(){
    public void run() {
        //do something
    }
});

// Runnable
// wrap function:
threadPool.execute(KouplelessCallable.wrap(new Callable<String>(){
    public String call() {
        //do something
        return "mock";
    }
});

// or new KouplelessRunnable
threadPool.execute(new KouplelessCallable<String>(){
    public String call() {
        //do something
        return "mock";
    }
});

2. Customize ThreadPoolExecutor

The original method:

ThreadPoolExecutor threadPool = new ThreadPoolExecutor(5, 5, 0L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue<Runnable>());

threadPool.execute(new Runnable(){
    public void run() {
        //do something
    }
});


threadPool.execute(new Callable<String>(){
public String call() {
        //do something
        return "mock";
 }
});

To keep Runnable and Callable unchanged, there are two ways to modify:

1. Change threadPool to KouplelessThreadPoolExecutor
2. Or use kouplelessExecutorService.

First, let’s take an example of the first modification method: change threadPool to KouplelessThreadPoolExecutor. As follows:

// modify ThreadPoolExecutor as KouplelessThreadPoolExecutor
ThreadPoolExecutor threadPool = new KouplelessThreadPoolExecutor(5, 5, 0L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue<Runnable>());

threadPool.execute(new Runnable(){
    public void run() {
        //do something
    }
});


threadPool.execute(new Callable<String>(){
public String call() {
        //do something
        return "mock";
 }
});

Then, illustrate the second method of modification: using kouplelessExecutorService. As follows:

// use kouplelessExecutorService
ExecutorService executor        = new KouplelessExecutorService(new ThreadPoolExecutor(5, 5, 0L, TimeUnit.MILLISECONDS, new LinkedBlockingQueue<Runnable>()));

// use executor to execute task
executor.execute(new Runnable(){
    public void run() {
        //do something
    }
});
executor.execute(new Callable<String>(){
public String call() {
        //do something
        return "mock";
 }
});

3. Use ThreadPoolExecutor or ScheduledThreadPoolExecutor from the third-party libraries.

The original method:

ThreadPoolExecutorA executorService = new ThreadPoolExecutorA();

executorService.execute(new Runnable(){
    public void run() {
        //do something
    }
});


executorService.execute(new Callable<String>(){
public String call() {
        //do something
        return "mock";
 }
});

ScheduledThreadPoolExecutorA scheduledExecutorService = new ScheduledThreadPoolExecutorA();

scheduledExecutorService.execute(new Runnable(){
    public void run() {
        //do something
    }
});

scheduledExecutorService.execute(new Callable<String>(){
    public String call() {
        //do something
        return "mock";
    }
});

To keep Runnable and Callable unchanged, it is necessary to use kouplelessExecutorService and kouplelessScheduledExecutorService, as follows:

// use KouplelessExecutorService
        ExecutorService executor        = new KouplelessExecutorService(new ThreadPoolExecutorA());

// use executor to execute tasks
executor.execute(new Runnable(){
    public void run() {
        //do something
    }
});
executor.execute(new Callable<String>(){
    public String call() {
        //do something
    return "mock";
    }
});

// use scheduledExecutorService 
ScheduledExecutorService scheduledExecutor = new KouplelessScheduledExecutorService(new ScheduledThreadPoolExecutorA());

// use scheduledExecutor to execute tasks
scheduledExecutor.execute(new Runnable(){
    public void run() {
        //do something
    }
});
scheduledExecutor.execute(new Callable<String>(){
    public String call() {
        //do something
        return "mock";
    }
});

4. Create thread pools through Executors

The original method:

ExecutorService executorService = Executors.newFixedThreadPool(6);

executorService.execute(new Runnable(){
    public void run() {
        //do something
    }
});


executorService.execute(new Callable<String>(){
public String call() {
        //do something
        return "mock";
 }
});

ScheduledExecutorService scheduledExecutorService = Executors.newSingleThreadScheduledExecutor();

scheduledExecutorService.execute(new Runnable(){
    public void run() {
        //do something
    }
});

scheduledExecutorService.execute(new Callable<String>(){
    public String call() {
        //do something
        return "mock";
    }
});

To keep Runnable and Callable unchanged, it is necessary to use kouplelessExecutorService and kouplelessScheduledExecutorService, as follows:

// use KouplelessExecutorService
ExecutorService executor        = new KouplelessExecutorService(Executors.newFixedThreadPool(6));

// use executor to execute tasks
executor.execute(new Runnable(){
    public void run() {
        //do something
    }
});
executor.execute(new Callable<String>(){
    public String call() {
        //do something
    return "mock";
    }
});

// use KouplelessScheduledExecutorService
ScheduledExecutorService scheduledExecutor = new KouplelessScheduledExecutorService(Executors.newSingleThreadScheduledExecutor());

// use scheduledExecutor to execute tasks
scheduledExecutor.execute(new Runnable(){
    public void run() {
        //do something
    }
});
scheduledExecutor.execute(new Callable<String>(){
    public String call() {
        //do something
        return "mock";
    }
});

5. For SpringBoot users, submit tasks to ThreadPoolTaskExecutor, SchedulerThreadPoolTaskExecutor

Due to koupeless having already adapted ThreadPoolTaskExecutor and SchedulerThreadPoolTaskExecutor for springboot (2.3.0-2.7.x), they can be used directly.

@Autowired
private ThreadPoolTaskExecutor threadPoolTaskExecutor;

@Autowired
private SchedulerThreadPoolTaskExecutor schedulerThreadPoolTaskExecutor;

threadPoolTaskExecutor.execute(new Runnable(){
    public void run() {
        //do something
    }
});

schedulerThreadPoolTaskExecutor.execute(new Runnable(){
    public void run() {
        //do something
    }
});

4.3.9 - 4.3.9 Multiple Configurations for Modules

Why Use Multiple Configurations

In different scenarios, a module’s code may be deployed to different applications but require different configurations.

How to Use

Step 1: When packaging a module’s code for different scenarios, configure different bizName, such as biz1, biz2.

<plugin>
    <groupId>com.alipay.sofa</groupId>
    <artifactId>sofa-ark-maven-plugin</artifactId>
    <version>${sofa.ark.version}</version>
    <executions>
        <execution>
            <id>default-cli</id>
            <goals>
                <goal>repackage</goal>
            </goals>
        </execution>
    </executions>
    <configuration>
        <!-- Configure different bizName for different scenarios, such as biz1, biz2 -->
        <bizName>biz1</bizName>
        <!-- ... Other properties -->
    </configuration>
</plugin>

Step 2: In the resources directory of the module, add the following files, where config , biz1 and biz2 are folders:

• config/biz1/application.properties
• config/biz2/application.properties Step 3: Package two different ark-biz files with different bizName values (biz1, biz2):
• biz1-0.0.1-SNAPSHOT-ark-biz.jar
• biz2-0.0.1-SNAPSHOT-ark-biz.jar Step 4: Install the corresponding ark-biz module for different scenarios. When the module starts, it will read the configuration files based on the bizName value:
• config/biz1/application.properties
• config/biz2/application.properties

Principle

When the module starts, it reads the following files as property sources based on the module name and spring.profiles.active field:

• config/${bizName}/application-${profile}.properties
• config/${bizName}/application.properties If spring.profiles.active is not set, it reads the following file as the property source:
• config/${bizName}/application.properties

4.3.10 - 4.3.10 Multimodule Integration Testing

Why Do We Need an Integration Testing Framework?

Without an integration testing framework, the validation steps for developers when verifying koupleless module logic can be cumbersome and involve the following steps:

1. Start a base process.
2. Build the module JAR package.
3. Install the module.
4. Call the module’s HTTP interface (or other methods) to validate the logic. If the logic does not meet expectations, developers need to repeat the above steps, making such a validation process highly inefficient. To improve the validation efficiency for developers, we decided to provide the koupleless integration testing framework, allowing developers to start both the base and the module within a single process.

Integration Testing Framework

Principle

The integration testing framework simulates a multi-module deployment scenario by enhancing the class loading behavior of the base and the modules. The specific source code can be referenced in koupleless-test-suite.

How to Use

Taking webflux-samples as an example, the project structure of webflux-samples is as follows:

• demowebflux: Base Code.
• bizwebflux: Module Code.

We create a new Maven module:

• webflux-integration-test: Integration Testing Module.

First, this module needs to add the integration testing framework dependency:

<dependency>
    <groupId>com.alipay.sofa.koupleless</groupId>
    <artifactId>koupleless-test-suite</artifactId>
    <version>${koupleless.runtime.version}</version>
</dependency>

Next, we need to add the dependencies for the base and the module:

<!-- Base Dependency -->
<dependency>
    <groupId>com.alipay.sofa.web.webflux</groupId>
    <artifactId>demowebflux</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <classifier>lib</classifier>
</dependency>
<!-- Module Dependency -->
<dependency>
    <groupId>com.alipay.sofa.web.webflux</groupId>
    <artifactId>bizwebflux</artifactId>
    <version>0.0.1-SNAPSHOT</version>
</dependency>

Then, we need to write the integration test case:

public static void setUp() {
    TestMultiSpringApplication multiApp = new TestMultiSpringApplication(
            MultiSpringTestConfig
                    .builder()
                    .baseConfig(
                            BaseSpringTestConfig
                                    .builder()
                                    // Pass in the base application's startup class.
                                    .mainClass(DemoWebfluxApplication.class)
                                    .build()
                    )
                    .bizConfigs(
                            Lists.newArrayList(
                                    BizSpringTestConfig
                                            .builder()
                                            .bizName("biz")
                                            // Pass in the module's startup class.
                                            .mainClass(BizWebfluxApplication.class)
                                            .build()))
                    .build());
    multiApp.run();
}