祝融说。

"The best time to plant a tree was 20 years ago. The second best time is now." — Chinese Proverb

Theory is gray, but the tree of life is ever green. In the preceding chapters, we have painted a picture of an ideal system after "conceptual decompression." But the reality most of us face is not a blank canvas. It is an old map, already scribbled over chaotically with layers of history -- a legacy system.

A legacy system is like an old, dilapidated house. Its foundation (the data model) has long settled, its walls (the code logic) are riddled with cracks, and its pipes (the business processes) are an intricate tangle. Every minor change risks triggering a "structural collapse." We cannot simply tear it down and rebuild, because the business -- the owner of this old house -- still lives in it and cannot move out for a single day.

So how do we perform "hot work" on this occupied house, safely and smoothly transforming it into the structure we envision?

This section will provide you with an actionable, battle-tested refactoring methodology. We will no longer discuss why to refactor; we will focus entirely on how to refactor. We will break the entire refactoring process into three major phases -- Identification, Migration, and Anti-Corruption -- and offer specific tools, techniques, and strategies for each.

Think of this as an action manual for the software "urban renewal" engineer. It will show you how to find the most dangerous condemned buildings in the old city, how to provide temporary housing for the residents (the business), how to safely demolish the old structures, and ultimately, on the same site, erect a more solid, clear, and beautiful modern edifice.

Prologue: Surgical-Style Refactoring

The worst thing you can do when refactoring a legacy system is to go "big and bold" and try to do it all at once. That kind of "big-bang refactoring" almost always ends in failure. Either it is abandoned midway because the risk is too high and the cycle too long, or it triggers a deployment disaster worse than the original system's problems upon going live.

We must adopt a "surgical-style" refactoring strategy. The core of this strategy is:

• Precise Diagnosis: Before making any moves, invest enough time in precisely locating the lesion.
• Minimally Invasive Intervention: Each change should be as small as possible, targeting only one clearly defined problem point.
• Vital Signs Monitoring: Throughout the surgery (the refactoring process), there must be comprehensive monitoring and verification mechanisms to ensure the "patient" (the system) maintains stable "vital signs" (business correctness).
• Gradual Recovery: Through a series of small, successful, verifiable operations, gradually improve the patient's overall health.

In this chapter, we will translate this "surgical" philosophy into a practical roadmap divided into two phases: the Identification Phase and the Migration Phase. We will learn, like an experienced surgeon, to first find the tumor using a CT scan and MRI (static analysis), then design a precise, minimally invasive surgical plan involving dual-writes and canary releases, and ultimately, safely excise it.

Section 1: The Identification Phase -- How to Find the Most Logic-Dense "Compression Points" Through Static Analysis

Before performing "conceptual decompression" on a legacy system, the primary question we face is: where to start?

A large legacy system may contain thousands of classes and tens of thousands of lines of code, full of all kinds of bad smells. If we intuitively pick a random starting point, we might get bogged down in an insignificant detail, expending a great deal of effort with little improvement in the overall complexity of the system.

We need a systematic, data-driven method to locate those "compression points" with the highest complexity and greatest refactoring payoff. These compression points are precisely where the "universal fields" and "exceptional case logic" we discussed in previous chapters are most concentrated. This process is like performing a comprehensive health check on our system using a "code complexity CT scanner."

The Toolbox: Your Complexity CT Scanner

Fortunately, we do not need to manually read every line of code. The community has already provided many powerful static code analysis tools that can help us quantify and visualize code complexity.

Cyclomatic Complexity

• What it is: A metric that measures the number of logical branches in a piece of code. A code block without if, for, while, or switch has a cyclomatic complexity of 1. Each additional branch increases the complexity by 1.
• Why it matters: Methods with high cyclomatic complexity are the most concentrated disaster zones for exceptional case logic. A method with a cyclomatic complexity exceeding 20 is almost certainly packed with deeply nested if/else statements -- a classic symptom of a missing data model.
• How to scan:
  • Java: Use tools like Checkstyle, PMD, or SonarQube. They all have built-in cyclomatic complexity check rules. Configure a threshold (e.g., alert above 15) and run the scan.
  • Python: Use the radon or wily library.
  • JavaScript/TypeScript: ESLint with the eslint-plugin-complexity plugin.
• Scan Results: You will get a list of methods sorted by cyclomatic complexity in descending order. The methods at the very top are your primary refactoring targets!

Afferent/Efferent Coupling

• What it is:
  • Afferent Coupling: How many other classes or modules depend on this class.
  • Efferent Coupling: How many other classes or modules this class depends on.
• Why it matters: A class or method with extremely high afferent coupling (called by many places) is usually a critical hub of the system. Refactoring it will have a wide impact and requires extra caution. A class with extremely high efferent coupling, on the other hand, might be a "God Class" -- it knows too much and does too many things outside its scope.
• How to scan: Comprehensive platforms like SonarQube can provide class-level coupling analysis reports. Some IDE plugins (such as IntelliJ IDEA's MetricsReloaded) can also do this.
• Scan Results: Look for classes with "high afferent, low efferent" (typically stable core entities or utility classes) and "high afferent, high efferent" (dangerous God Classes that may be the focus of refactoring).

Code Duplication Rate

• What it is: Detects similar or identical code blocks in the codebase.
• Why it matters: Large blocks of duplicate code, especially those containing business logic judgments, often hint at an unabstracted generic rule. When we see similar if (user.getType() == ...) checks in multiple places, it is a strong signal that the user.type concept needs to be decompressed and its judgment logic unified and encapsulated in one place -- such as a configuration table or a dedicated service.
• How to scan: PMD's CPD (Copy-Paste Detector) function, SonarQube's duplicate code detection.
• Scan Results: Focus on duplicate business logic that spans different modules.

Diagnostic Process: Three Steps to Locate the Core Lesions

With the tools in hand, we can begin systematic diagnosis.

Step One: Global Scan, Draw a Heat Map Run a comprehensive static analysis on the entire codebase to generate a "health report" containing metrics like cyclomatic complexity, coupling, lines of code, and duplication rates. Do not dive into the details yet; first get a macro-level understanding of the system's complexity distribution.

SonarQube's dashboard is an excellent tool for this. Like a heat map, it will use red and orange to mark the most pathological modules and classes.

Your goal: Find classes or methods that are flagged red across multiple dimensions -- for example, both high cyclomatic complexity and large lines of code. These are what we call "the most logic-dense compression points."

Step Two: Focus on the Target, Read the Suspects From the heat map, select the top 3-5 methods or classes with the highest complexity as your first batch of refactoring targets. Now you need to start reading the code of these suspects in depth.

Read with these questions in mind:

1. What is this method's if/else or switch judging?
   • Is it judging a type or status field? If so, congratulations -- you have found a typical "universal field" ready for the dimension decomposition method from Chapter 3.
2. Are these judgment branches handling exceptional cases?
   • Does the code have hard-coded checks like if (id == ...) or if (name.equals("..."))? If so, you have found a rule that needs data-ification, ready for the "eliminate exceptional cases" method from Chapter 4.
3. What is this method's responsibility? Is it doing too much?
   • Does it simultaneously handle business operations and permission checks? Is it responsible for both state transitions and historical records? If so, you have found a scenario requiring separation of concerns, ready for the spacetime separation and separation of concerns principles from Chapters 5 and 6.

Case Analysis: Suppose our scan reveals that the OrderService.processNewOrder method has a cyclomatic complexity of 50. Reading the code, we find a large switch (order.getType()) with nested order.getStatus() checks in each case.

Diagnostic Conclusion:

• Lesions: order.type and order.status are two highly compressed "universal fields."
• Surgical Plan: Apply the dimension decomposition method to split order.type into independent dimensions like billing_model and flow_type. Apply the Snapshot Pattern to record the change history of order.status in a separate log table.

Step Three: Impact Analysis, Assess Surgical Risk After confirming the surgical plan, we also need a critical preoperative assessment -- impact analysis.

Use your IDE (such as IntelliJ IDEA's "Find Usages" function) or static analysis tools to find:

1. Who calls this high-complexity method?
2. Where else in the system are the universal fields (e.g., order.type) read or modified?

This analysis is crucial; it determines the scope and difficulty of our surgery.

• If order.type is only used within this method, refactoring is relatively simple and safe.
• If order.type is read in hundreds of places across the system, our migration process must be designed with extreme care, ensuring that the refactoring does not affect those bystanders relying on the old field.

After completing the Identification Phase, we have a clear, prioritized refactoring task list, along with an initial surgical plan and risk assessment for each task. Now we can put on our gloves, enter the operating room, and begin the next phase -- Migration.

Section 2: The Migration Phase -- How to Safely Move Logic from Code to the Database

"Migration" is a vivid metaphor for the conceptual decompression refactoring process. Its core is to gradually and safely move business judgment logic, originally hard-coded in the code, into the database -- into a new field or a new configuration table.

This process is like replacing the track system for a high-speed railway while trains are still running. We absolutely cannot simply stop all trains, work for a few days, and then resume service. We must complete the track replacement quietly while ensuring the existing trains (the online business) continue to operate normally.

To achieve this seamless migration, we need a powerful, proven set of engineering practices. The most central of these is the "Dual-Write, Canary-Release, Switch-Over" trilogy.

The "Dual-Write, Canary-Release, Switch-Over" Trilogy

Let us walk through this process using the refactoring of the order.type field as a complete example. Our goal is to replace the old order.type with the new dimensional fields billing_model and flow_type.

Phase One: Preparation -- Laying the New Track

Before starting dual-writes, we must complete all the preparation work.

1. Modify the database schema:

   • Add new fields to the t_order table: billing_model (varchar), flow_type (varchar). Allow them to be NULL.
   • ALTER TABLE t_order ADD COLUMN billing_model VARCHAR(50) NULL, ADD COLUMN flow_type VARCHAR(50) NULL;
   • Note: For large tables, this operation might lock the table. It should be performed during a low-traffic period under the guidance of a DBA, or using tools like pt-online-schema-change.

2. Create a translation layer:

   • Create an OrderTypeTranslator class whose responsibility is to implement bidirectional mapping between old and new data.
   • translateFromOld(int oldType): This method receives the old order.type value and returns an object containing billing_model and flow_type.
   • translateToOld(String billingModel, String flowType): This method is for reverse mapping. While not commonly used, it may be needed during certain transitional phases.

3. Deploy preparation code: Deploy the modified database ORM entity class (with the new fields) and OrderTypeTranslator to production.

   • At this point, no code is using these new fields or new logic. This step simply makes our application aware of the existence of the new track. The risk is extremely low.

Phase Two: Dual-Write -- Old and New Tracks Running in Parallel

This is the most critical and also the longest phase of the migration. In this phase, we ensure that every write operation to the old data is also synchronously and atomically written to the new data.

1. Refactor all write entry points:

   • Find all places that create or modify Order objects. These are typically OrderRepository.save(), OrderService.createOrder(), and OrderService.updateOrder() methods.
   • Insert dual-write code at the core logic of these methods.

   // OrderService.java
   @Transactional
   public Order createOrder(OrderCreationRequest request) {
       Order order = new Order();
       // ... set various business attributes ...
   
       // Old logic: set order.type
       int oldType = determineOrderType(request); // This is a complex old method
       order.setType(oldType);
   
       // (Core) Dual-write logic
       NewDimensions dimensions = translator.translateFromOld(oldType);
       order.setBillingModel(dimensions.getBillingModel());
       order.setFlowType(dimensions.getFlowType());
   
       return orderRepository.save(order);
   }
   

2. Handle existing data:

   • For historical data that existed before the dual-write went live, the new fields will be NULL. We need to run a one-time background data migration script to backfill these values.
   • This script will batch-read old data from the t_order table, call translator.translateFromOld(), and batch-update the new fields.
   • Note: This script must be re-entrant and idempotent. It should be able to be interrupted and restarted, and can be run repeatedly without side effects.

Goal of the dual-write phase: After a period of operation and existing data backfill, we should reach a state where the new fields (billing_model, flow_type) and the old field (type) in the t_order table are logically fully synchronized. We can verify this synchronization by writing a validation script that randomly samples data.

Phase Three: Canary Read -- Gradually Directing Traffic to the New Track

Once data-level synchronization between old and new is achieved, we can begin to guide the business logic to gradually switch from reading old data to reading new data. This process must be canary-based and controllable.

1. Refactor business logic:

   • Find all places where order.getType() is read for decision-making (these are the high-complexity code locations we identified in the Identification Phase).
   • Rewrite this old logic using new logic based on the new fields (order.getBillingModel(), order.getFlowType()). Keep both the old and new logic sets in place.

   // PriceCalculator.java
   public Money calculatePrice(Order order) {
       // Use a feature flag to control whether to use new or old logic
       if (featureFlags.isUseNewOrderDimensionsEnabled(order.getId())) {
           // (New logic)
           if ("CORPORATE_MONTHLY".equals(order.getBillingModel())) {
               // ...
           }
       } else {
           // (Old logic)
           if (order.getType() == 10) {
               // ...
           }
       }
   }
   

2. Introduce feature flags:

   • Feature flags are the core tool for achieving safe canary releases. They allow us to dynamically control which code branch executes at runtime, without redeployment.
   • We can use mature feature flag systems (such as LaunchDarkly or Unleash), or implement a simple one ourselves based on a configuration center or database.
   • The granularity of the flag can be very flexible:
     • By percentage: First, let 1% of traffic use the new logic and observe the monitoring.
     • By user ID whitelist: First, let our internal test accounts use the new logic.
     • By order ID: order.getId() % 100 < 5 (5% of traffic).

3. Verification and monitoring:

   • During the canary period, the most important thing is to verify the equivalence of the old and new logic. We can do this through shadow testing or side-by-side comparison.
   • Shadow testing: Execute both old and new logic simultaneously, but only return the result from the old logic. Record the differences between the results in the background for analysis.
   • Monitoring: Closely monitor core business metrics (such as order success rate, payment amount, and GMV). If traffic using the new logic shows any abnormal fluctuation in business metrics, immediately turn off the flag and all traffic instantly rolls back to the old logic.

Goal of the canary-read phase: Through gradual traffic increase and rigorous monitoring, ultimately reach a state where 100% of traffic is safely and correctly running on the new logic. We are confident that the new logic is a perfect replacement for the old logic.

Phase Four: Switch-Over and Cleanup -- Dismantling the Old Track

Once the new logic has been fully rolled out to 100% and has been running stably for a period (such as a week), we can enter the final cleanup phase.

1. Switch the write entry point:

   • Refactor createOrder and other write entry points to natively use the new data, then use translator.translateToOld() to generate the old order.type value in reverse, for compatibility with any read code in the system that has not yet been refactored.
   • After this step, the new data becomes the authoritative source, and the old data becomes a compatibility artifact.

2. Clean up read code:

   • After confirming that all read logic depending on order.getType() has been refactored, we can delete the old logic branches and feature flags from the if/else statements. The code becomes clean and tidy.

3. Stop dual-write:

   • Remove the logic that generates old data in reverse in createOrder. Now, the order.type field for new orders will be NULL.

4. Decommission the old field:

   • This is the final and most satisfying step. After confirming that no code or script depends on the old field, we can physically delete the order.type field from the database.
   • ALTER TABLE t_order DROP COLUMN type;
   • Surgery complete. The tumor has been completely removed.

Roadmap Summary

This roadmap breaks down a seemingly huge and dangerous refactoring task into a series of small, safe, verifiable steps. It replaces heroic gambling with rigorous engineering. It may seem slow, but as an old engineering saying goes: "Slow is smooth, and smooth is fast."

Chapter Summary: Refactoring is Engineering, Not Art

In this chapter, we have provided a detailed, executable surgical guide for legacy system governance. We have emphasized that successful refactoring is not an artistic creation sparked by inspiration, but a systems engineering task that follows a rigorous process.

We first explored the Identification Phase. We learned how to use static analysis tools -- cyclomatic complexity, coupling metrics, and more -- like a CT scanner to data-drivenly locate the most logic-dense compression points in the system. We emphasized the importance of deep code reading and impact analysis before taking action, which helps us formulate the correct surgical plan and assess risk.

We then detailed the core process of the Migration Phase -- the "Dual-Write, Canary-Release, Switch-Over" trilogy. This is an industrial-grade migration paradigm designed to ensure business continuity and safety:

• Starting with preparation and dual-write, we quietly achieved old and new parallelism at the data level.
• Through canary reading and feature flags, we achieved precise traffic control and instantaneous risk rollback at the logic level.
• Finally, in the switch-over and cleanup phase, we safely removed historical baggage, rejuvenating the system.

The core philosophy of this roadmap is "incremental evolution" and "risk control." It breaks a huge, uncertain problem into a series of small, deterministic sub-problems, each of which can be verified step by step.

Now, you possess both the technique and the philosophy of refactoring. You understand not only the profound principles of conceptual decompression, but also how to apply them safely to real-world complex systems.

However, successful surgery is only the first step toward recovery. How do we prevent a relapse? How do we establish a mechanism that allows our system to naturally resist the erosion of conceptual compression during future evolution? That is the topic of the final chapter of this book -- establishing a new set of team collaboration and code review standards to build the system's anti-corruption mechanism.