Debug Tools Development Guidelines

Project Overview

Debug Tools is a multi-module Java project with an IntelliJ IDEA plugin that provides advanced debugging capabilities including hot-deploy, hot-reload, method invocation, SQL monitoring, and remote debugging.

Key Capabilities

•Hot Deploy: Skip build/deploy cycle - changes take effect without manual triggers
•Hot Reload: Code changes apply instantly without restarting (supports classes, proxies, Spring, Solon, MyBatis)
•Method Invocation: Directly invoke any Java method without API layers
•Remote Debugging: Trigger remote methods with hot-deploy support
•SQL Monitoring: Print SQL statements and execution time without code changes
•HTTP URL Search: Navigate from URL to method definition
•xxl-job Support: Execute client methods with context passing
•Groovy Execution: Run Groovy scripts for debugging

Module Structure

Maven Modules (root: `pom.xml`)

code

debug-tools/
├── debug-tools-attach          # Attachment agent
├── debug-tools-common          # Shared utilities, DTOs, protocols
├── debug-tools-test            # Test modules and examples
├── debug-tools-base            # Base functionality
├── debug-tools-server          # Server-side components
├── debug-tools-client          # Client-side components (Netty-based)
├── debug-tools-boot            # Bootstrap and initialization
├── debug-tools-core            # Core debugging functionality
├── debug-tools-hotswap         # Hot swap agent with plugin system
├── debug-tools-vm              # VM-related utilities
├── debug-tools-sql             # SQL monitoring
└── debug-tools-extension       # Extensions (Spring, Solon)

IDEA Plugin Module (Gradle: `debug-tools-idea/`)

code

debug-tools-idea/
├── src/main/java/io/github/future0923/debug/tools/idea/
│   ├── action/                 # IDEA actions (menus, shortcuts)
│   ├── client/socket/          # TCP client for server communication
│   ├── listener/data/          # Data event listeners
│   ├── context/                # Context helpers (class/method data)
│   └── camel/                  # Naming convention converters
└── build.gradle.kts            # Gradle build configuration

Package Structure Standards

Common Module (`debug-tools-common`)

code

io.github.future0923.debug.tools.common/
├── codec/                      # Netty encoding/decoding
├── dto/                        # Data Transfer Objects
│   ├── RunDTO.java
│   ├── RunContentDTO.java
│   ├── RunResultDTO.java
│   └── TraceMethodDTO.java
├── enums/                      # Enumerations
│   ├── PrintResultType.java
│   ├── ResultClassType.java
│   ├── ResultVarClassType.java
│   └── RunContentType.java
├── exception/                  # Custom exceptions
│   ├── DebugToolsException.java
│   ├── DebugToolsRuntimeException.java
│   ├── ArgsParseException.java
│   └── CallTargetException.java
├── handler/                    # Netty packet handlers
├── protocal/                   # Protocol definitions
│   ├── packet/                 # Packet base and types
│   │   ├── Packet.java
│   │   ├── EntityPacket.java
│   │   ├── request/            # Request packets
│   │   └── response/           # Response packets
│   ├── http/                   # HTTP protocol objects
│   └── serializer/             # Serialization implementations
└── utils/                      # Utility classes
    ├── DebugToolsJsonUtils.java
    ├── DebugToolsTypeUtils.java
    ├── DebugToolsLambdaUtils.java
    ├── DebugToolsDateUtils.java
    └── JdkUnsafeUtils.java

Hot Swap Module (`debug-tools-hotswap`)

code

io.github.future0923.debug.tools.hotswap.core/
├── HotswapAgent.java          # Main agent entry point
├── annotation/                # Plugin annotation system
│   ├── Plugin.java
│   ├── Init.java
│   ├── OnClassFileEvent.java
│   ├── OnClassLoadEvent.java
│   ├── OnResourceFileEvent.java
│   └── handler/               # Annotation processors
├── command/                   # Command system
│   ├── Command.java
│   ├── MergeableCommand.java
│   ├── Scheduler.java
│   └── impl/                  # Implementations
├── config/                    # Configuration
│   ├── PluginManager.java
│   ├── PluginConfiguration.java
│   └── PluginRegistry.java
├── plugin/                    # Built-in plugins
│   ├── hotswapper/            # Hot swap implementation
│   ├── watchResources/        # Resource watching
│   └── gson/jackson/spring/   # Framework-specific plugins
├── util/                      # Utilities
│   ├── JavassistUtil.java     # Bytecode manipulation
│   ├── ReflectionHelper.java
│   ├── HotswapTransformer.java
│   ├── AnnotationHelper.java
│   ├── IOUtils.java
│   ├── classloader/           # ClassLoader utilities
│   └── scanner/               # Class scanning
└── watch/                     # File watching
    ├── Watcher.java
    ├── WatcherFactory.java
    └── nio/                   # NIO2 implementation

Code Style and Conventions

Import Statements

•Follow standard Java import conventions
•Group imports logically: standard library, third-party, project imports
•Use spotless-maven-plugin for automatic formatting

Naming Conventions

•Classes: PascalCase (e.g., RunTargetMethodRequestPacket)
•Methods: camelCase (e.g., dispatchPacket)
•Constants: UPPER_SNAKE_CASE (e.g., PORT)
•Packages: lowercase with dots (e.g., io.github.future0923.debug.tools.common)

Exception Handling

•Create domain-specific exceptions extending DebugToolsException or DebugToolsRuntimeException
•Provide descriptive error messages
•Include relevant context in exception data

Logging

•Use SLF4J for logging
•Configure logging levels appropriately
•For hotswap operations, see LogConfigurationHelper

Lombok Usage

•Lombok is used throughout the project (version 1.18.38)
•Common annotations: @Data, @Slf4j, @Builder, @AllArgsConstructor, @NoArgsConstructor

Protocol and Packet Design

Packet Structure

All packets extend Packet:

java

public abstract class Packet {
    // Common packet fields
    protected Command command;
    protected int sequenceId;
    // ...
}

Request/Response Pattern

•Request packets: XxxRequestPacket (in protocal/packet/request/)
•Response packets: XxxResponsePacket (in protocal/packet/response/)
•Use command enum in Command for packet type identification

Serialization

•Default serializer: BinaryNettySerializer
•Implement NettySerializer for custom serialization
•Register serializers in SerializerAlgorithm

Netty Communication

Client-Side (debug-tools-client / debug-tools-idea)

•Client dispatcher: ClientNettyPacketDispatcher (Netty) or ClientPacketDispatcher (Socket)
•Handlers are registered in ClientDispatchHandler

Common Codecs

•Encoder: PacketNettyEncoder
•Decoder: PacketNettyDecoder
•Frame decoder: PacketFrameDecoder

Server-Side (debug-tools-server)

•Handlers implement NettyPacketHandler

Hot Swap Plugin System

Plugin Development

Hot swap uses a plugin architecture. To create a new plugin:

•Create plugin class with @Plugin annotation
•Use @Init for initialization
•
Use event annotations:
- •@OnClassFileEvent - Class file changes
- •@OnClassLoadEvent - Class loading events
- •@OnResourceFileEvent - Resource file changes

Example plugin structure:

java

@Plugin(name = "MyPlugin", version = "1.0.0")
public class MyPlugin {
    
    @Init
    public void init(PluginConfiguration config) {
        // Initialization logic
    }
    
    @OnClassFileEvent
    public void onClassChange(ClassFileEvent event) {
        // Handle class changes
    }
}

Bytecode Manipulation

•Use JavassistUtil for bytecode operations
•ClassFileTransformer implementations: HaClassFileTransformer
•
See existing plugins for patterns:
- •HotSwapperPlugin
- •WatchResourcesPlugin

IDEA Plugin Development

Action Structure

All IDEA actions extend base classes:

•AbstractTraceMethodAction - For method tracing
•Actions are registered in plugin.xml (referenced in build.gradle.kts)

Client Communication

•TCP client: DebugToolsTcpClient
•Config: ClientConfig
•State tracking: ClientConnectState

Context Helpers

•ClassDataContext - Class information
•MethodDataContext - Method information

Build and Development

Maven Build

bash

# Build entire project
mvn clean install

# Build specific module
cd debug-tools-common
mvn clean install

# Skip tests
mvn clean install -DskipTests

Gradle Build (IDEA Plugin)

bash

cd debug-tools-idea
./gradlew buildPlugin

# For Windows
gradlew.bat buildPlugin

Code Formatting

•spotless-maven-plugin runs automatically on validate phase
•Manually format: mvn spotless:apply

License Formatting

•license-maven-plugin runs automatically on validate phase
•See HEADER file for license template

Testing

Test Modules

•
debug-tools-test/ contains test applications:
- •debug-tools-test-simple - Simple test case
- •debug-tools-test-spring-boot-mybatis - Spring Boot + MyBatis example

Running Tests

bash

# Run all tests
mvn test

# Run tests with hotswap agent (JDK < 21)
mvn test -P surefire-java-lt21

Test Configuration

Hotswap tests require special JVM arguments (see surefire-java-lt21 profile in pom.xml):

bash

-XX:+AllowEnhancedClassRedefinition
-XX:HotswapAgent=external
--add-opens java.base/java.lang=ALL-UNNAMED
--add-opens java.base/jdk.internal.loader=ALL-UNNAMED
# ... more opens

Dependencies

Key Versions

•Java: 8+ (supports 8, 11, 17, 21, 25)
•Spring Boot: 2.7.4
•Groovy: 4.0.22
•Javassist: 3.30.2-GA
•Lombok: 1.18.38
•Hutool: 5.8.29
•Arthas: 3.7.2

Shadow/Relocated Packages

•Shaded package prefix: io.github.future0923.debug.tools.dependencies
•Use maven-shade-plugin to relocate third-party dependencies

Framework Integration

Spring Plugin

Location: debug-tools-hotswap/debug-tools-hotswap-plugin/debug-tools-hotswap-spring-plugin

•Supports Spring Boot 2.7.4
•Provides Spring context-aware hot reload

Solon Plugin

Location: debug-tools-extension/debug-tools-extension-solon

•Supports Solon 3.3.1
•Provides Solon framework integration

Jackson/Gson Plugins

•JacksonPlugin
•GsonPlugin

Development Workflow

•Code Changes: Make modifications in appropriate modules
•Build: Run mvn clean install for Maven modules
•Plugin Build: Run ./gradlew buildPlugin in debug-tools-idea
•Test: Use test applications in debug-tools-test
•IDEA Plugin: Install plugin jar from debug-tools-idea/build/distributions/

Important Files to Reference

•Main POM: pom.xml
•Hotswap Agent: HotswapAgent.java
•Client Config: ClientConfig.java
•Bootstrap: DebugToolsBootstrap.java
•IDEA Plugin Build: build.gradle.kts

Important Notes

•DO NOT execute mvn or other build commands during development
•DO NOT write test code
•Prompt users to manually build and verify changes

Debug Tools Development Guidelines

Project Overview

Key Capabilities

Module Structure

Maven Modules (root: pom.xml)

IDEA Plugin Module (Gradle: debug-tools-idea/)

Package Structure Standards

Common Module (debug-tools-common)

Hot Swap Module (debug-tools-hotswap)

Code Style and Conventions

Import Statements

Naming Conventions

Exception Handling

Logging

Lombok Usage

Protocol and Packet Design

Packet Structure

Request/Response Pattern

Serialization

Netty Communication

Client-Side (debug-tools-client / debug-tools-idea)

Common Codecs

Server-Side (debug-tools-server)

Hot Swap Plugin System

Plugin Development

Bytecode Manipulation

IDEA Plugin Development

Action Structure

Client Communication

Context Helpers

Build and Development

Maven Build

Gradle Build (IDEA Plugin)

Code Formatting

License Formatting

Testing

Test Modules

Running Tests

Test Configuration

Dependencies

Key Versions

Shadow/Relocated Packages

Framework Integration

Spring Plugin

Solon Plugin

Jackson/Gson Plugins

Development Workflow

Important Files to Reference

Important Notes

Maven Modules (root: `pom.xml`)

IDEA Plugin Module (Gradle: `debug-tools-idea/`)

Common Module (`debug-tools-common`)

Hot Swap Module (`debug-tools-hotswap`)