Developing backend systems for too long, the first thing to go rotten is usually not the complex business logic, but the assembly relationships among menus, routes, and permissions.

"This page clearly exists in the menu, but clicking the link gives an error"; "The URL works, but the buttons on the page have no permission"; "When adding a new page, I have to modify the menu, Router, title, breadcrumbs, and permission guard at the same time, and finally hope I didn't miss an if logic." Many middle-end and back-end projects aren't dragged down by business logic, but slowly worn out by these scattered "assembly boilerplates."

The following is an approach we've validated in a real project: Refuse to define menus, routes, and permissions separately; gather them into a unified "Page Model," dynamically assembled at runtime through a configuration center.

Even if your project doesn't use micro-frontends, the design idea of this model can be adopted independently.

Core Pain Points: Why Do Traditional Approaches Always Get Out of Control?

In the early stages of a project, people usually go with whatever is quickest:

Write one configuration for the menu.
Write another configuration for routes.
Use annotations or HOCs to guard permissions at component entries.
Create a separate mapping table for breadcrumbs and titles.

When there are few pages, a combination of manual copy-paste and memory can still hold things together. But once the business domains multiply and the team exceeds three people, this structure collapses faster than anything.

The essence of the problem boils down to one sentence: You are repeatedly defining the same thing in different places.

When a page simultaneously exists as a shadow in the menu, Router, permission guard, breadcrumb, and title generation logic, you are not actually maintaining the page; you are carefully maintaining five copies of "data consistency." As long as one deployment misses a single spot, the classic "menu visible, page inaccessible" error will appear in production.

Breakthrough: Consolidate Page Definitions into a Single Model

The core idea of this system is restrained: Instead of writing separate "best practices" for menus or routes, it converges the rights they should enjoy into a common hub—the Page Model.

From the perspective of the main shell, a page is not just a route string; it is a set of complete semantic declarations. Its TypeScript type looks like this:

// Permission declaration
interface IPermissionRequired {
    act: string;    // Action, supports wildcards like "Blog.*"
    res: string[];  // Resources, e.g., ["blog-cp:en:article", "blog-cp:de:article"]
}
 
// Page configuration – the core type of the entire system
interface IPageConfig {
    app: string;                    // Sub‑application it belongs to, e.g., "child-app-blog-admincp"
    url: string;                    // Route path, e.g., "/article"
    title: string;                  // Internationalization key, shared by menu, breadcrumb, tabs
    required: IPermissionRequired[];// Permissions required for access
    to?: string;                    // Default redirect
    children?: IChildPage[];        // Child pages
}

The corresponding pages.json looks like this:

{
    "app": "child-app-blog-admincp",
    "url": "/article",
    "to": "/",
    "title": "articleManagement",
    "required": [{
        "act": "Blog.*",
        "res": ["blog-cp:en:article", "blog-cp:de:article"]
    }],
    "children": [
        { "title": "createArticle", "url": "/create", "required": [...] }
    ]
}

With this single source of truth, all upper‑layer presentation logic can be directly derived from it:

The system uses a single definition to fully answer three questions: "What is this page, which application does it belong to, and who can access it?" When adding a new page, you only need to modify one JSON – if you find yourself needing to modify a second place, it means the model should be refactored.

Runtime Assembly: A Pipeline of Three Configuration Layers

To prevent the configuration file from becoming a massive JSON of tens of thousands of lines, we split it into three layers based on responsibility boundaries:

1. Environment Entry: `settings.json`

It does only one thing – tells the main shell "which configuration set to read for the current environment":

{
    "develop":    { "childApps": "childApps-develop.json",    "pages": "pages-develop.json" },
    "sandbox":    { "childApps": "childApps-sandbox.json",    "pages": "pages-sandbox.json" },
    "production": { "childApps": "childApps-production.json", "pages": "pages-production.json" }
}

When the main shell starts, it loads this first, then locates the correct filenames based on the current mode. This step is simple, but it is the starting point of the entire assembly chain – a wrong reading here will break everything downstream.

2. Sub‑Application Registry: `childApps.json`

Answers: "Which applications can be mounted in the system?" Each sub‑application declares its resource entry, sandbox policy, and keep‑alive status:

{
    "child-app-blog-admincp": {
        "url": "/child-app-blog-admincp/",
        "keepAlive": true,
        "disableSandbox": false,
        "entry": "index.html",
        "index": "article/"
    }
}

3. Core Business Tree: `pages.json`

Describes the system’s service groups → categories → pages → child pages → permission requirements from top to bottom. This is the heart of the entire framework; its structure has already been shown above.

These three layers are not simply read and forgotten when the main shell starts; they go through a strict construction pipeline:

The PageProcessor builds three indices in memory:

class PageProcessor {
    private _appIndex: Record<string, IPageIndexEntry[]> = {};    // Grouped by sub‑application
    private _routeIndex: Map<string, IPageIndexEntry> = new Map(); // O(1) route lookup
    private _pageKeyIndex: Map<string, IPageIndexEntry> = new Map(); // Query by key
}

The route key rule is simple: for top‑level pages, use app/path (e.g., child-app-blog-admincp/article); for child pages, use app/parentPath/childPath (e.g., child-app-blog-admincp/article/create). When the route changes, a single Map.get() retrieves all page metadata for the current URL without any traversal.

In conventional development, menus and routes often drift apart – menus serve "visual display," while routes serve "underlying navigation," each with its own lifecycle.

Our approach here is: The menu completely surrenders configuration authority; it is merely a shadow of the page tree under specific permissions.

The Menu component directly fetches data from the Pages module and recursively builds itself:

// Menu component: does not maintain its own menu data
const pageList = pages.getPages(); // Already a tree filtered by permissions
 
// getMenuItem recursively generates an Ant Design Menu structure
const menuItems = pageList.map(service =>
    getMenuItem(service, currentPage, translate)
);

The main shell router is even simpler – it does not hardcode any business routes; it only contains wildcard routes that serve as entry points for sub‑applications:

// Iterate over the childApps registry, generate one wildcard route per sub‑application
for (const app in appList) {
    routeItems.push(
        <Route
            path={app.url + '*'}
            key={app.name}
            element={<CompChildAppSite {...app} />}
        />
    );
}

What menus the user sees and which pages they can access within a sub‑application are all dynamically trimmed at runtime by pages.json. The platform layer holds the contracts and entry points; the business layer holds the specific implementations. The boundaries are clear.

Permission Is No Longer a Band‑Aid

Permission systems are often where middle‑end/back‑end systems go astray most easily. Many projects start with pages, and later, to patch security compliance, they begin to litter patches everywhere: an interceptor in the route guard, an if inside the component, and a fallback message when the API returns an error.

In this system, permissions are an inherent part of the page model. The verification is designed as a standard two‑layer mechanism:

Layer 1 is completed in Pages.init() – after obtaining the permissions set, the tree is directly trimmed, so inaccessible pages simply do not appear in the menu. The core logic is straightforward:

// Pages module: permission filtering
private _checkPermission(page: IPage): boolean {
    if (page.required.length === 0) return true; // No permission requirement = public page
 
    for (const { act, res } of page.required) {
        for (const resItem of res) {
            if (permissionChecker.check(act, resItem)) return true;
        }
    }
    return false;
}

Layer 2 is triggered on route changes – even if the user blindly types a URL, they cannot bypass the usePermission hook’s secondary verification:

// usePermission hook: re‑checked on every location change
const pageInfo = pages.getPageInfo(`${pathname}${hash}`);
const canGo = pageInfo.required.some(({ act, res }) =>
    res.some(r => permissionChecker.check(act, r))
);
dispatch(setCanGo({ canGo })); // false → 403

Both layers consume the exact same permission metadata. The developer only needs to declare the required field once in the JSON, and both the security boundary and the user experience are simultaneously covered.

Costs: No Silver Bullet

Configuration‑driven development brings consistency but also real trade‑offs:

1. The configuration model tends to bloat over time. Today you want to add a default menu collapse strategy, tomorrow a dynamic tab label, and the day after a badge for a certain page. If the initial modeling is not restrained, pages.json can eventually balloon into an obscure implicit DSL whose maintenance pain rivals that of writing bad code. Our approach: any new field must first be questioned – "Can this field be derived from existing fields?" If yes, it is not added.

2. Local development has a disconnect. Configuration is hosted in a Git repository and distributed via a configuration center. When developing a new page daily, you need to start a local configuration service to override the online JSON. The environment setup chain for new employees is noticeably longer than in traditional projects.

3. Debugging becomes longer. When a white screen or navigation error occurs in production, you cannot simply search globally for a route string and locate the component as you could before. The debugging chain is: Did settings read correctly? → Is the pages.json version published by the configuration center correct? → What does the permission‑trimmed page tree look like in memory? The improvement in consistency comes at the cost of a doubled debugging path.

Summary

What makes configuration‑driven valuable is never "writing code into JSON," but forcing you to re‑gather definitions scattered across every corner and establish a page model that all modules recognize. Menus, routes, permissions, breadcrumbs – they are not four separate problems. They are four manifestations of the same problem.

0 Comments

Leave a Comment