Umajs: A Lightweight Node.js Web Framework with Decorators, AOP, and Unified Result Handling

Umajs is an open‑source, lightweight Node.js web framework released by 58.com, designed to combine multiple packages into a cohesive, production‑ready solution. It emphasizes strong TypeScript support, rich built‑in decorators, IOC, AOP, and a unified return mechanism called Result .

Key Features

Rich decorator system (customizable decorators)

Dependency injection (IOC) eliminating manual imports and instantiation

Aspect‑Oriented Programming (AOP) via decorators for method‑level interception

Unified return handling (Result) for simplified response generation

Plugin mechanism compatible with Koa2 middleware

High stability and performance, written in TypeScript with full test coverage

Architecture Design

User request reaches the router

Router parses request through plugins and forwards to the controller

Controller accesses services/resources via IOC

Controller, service, and resource can be enhanced with AOP aspects

Controller returns a Result, which formats the response according to Koa conventions

Middleware can be used directly or wrapped as Aspect.around decorators

Plugins can be extended as middleware or composite forms

AOP (Aspect Oriented Programming)

AOP allows dynamic extension of functionality without modifying original code. Umajs provides five built‑in aspects: before: execute before the target method after: execute after the target method around: wrap the target method, receiving it as a parameter afterThrowing: execute when the target method throws an exception afterReturning: execute after the target method returns a value

Example of adding a reporting aspect to a method:

getList(params){
    // do something
    return list;
}

@Aspect.before('report')
getList(params){
    // do something
    return list;
}

This separates reporting logic from business logic, reducing coupling and improving reusability.

Unified Result Return

Traditional Node.js frameworks require manual response handling. Umajs introduces a concise Result API: Result.send(val, status): quick text response Result.json(data): JSON response Result.jsonp(data, callback): JSONP response Result.view(templatePath, data): render a view template Result.stream(data, fileName): stream file download Result.download(filePath, opts): file download

These shortcuts accelerate development and can be extended via plugins.

Custom Decorators

Umajs provides several built‑in decorators such as @Aspect, @Resource, @Inject, @Path, and @Private. Developers can also create parameter decorators using createArgDecorator:

const Query = createArgDecorator((argKey, ctx) => ctx.query[argKey]);

Example of a custom argument decorator for ID validation:

const IdCheck = createArgDecorator((key: string, ctx: IContext) => {
    const id = ctx.query[key];
    if (id === undefined || id === null || id === '') {
        return Result.json({
            code: ErrorType.Empty,
            msg: `参数 ${key} 不能为空`
        });
    }
    // other validation logic
    return id;
});
export IdCheck;

An aspect handling exceptions can be defined as:

export default class Demo implements IAspect {
    async around(proceedPoint: IProceedJoinPoint) {
        try {
            const { proceed, args } = proceedPoint;
            const result = await proceed(...args);
            return result;
        } catch (e) {
            return Result.json({
                code: ErrorType.Error,
                msg: e.toString()
            });
        }
    }
}

Applying the decorator and aspect to a controller method:

@Aspect('demo')
getList(@IdCheck('userid') uid) {
    const list = this.service.getListByUid(uid);
    return Result.json(list);
}

Core Advantages

Powerful built‑in decorators (IOC, AOP, routing) and extensibility for custom decorators

Flexible plugin mechanism compatible with Koa middleware

Unified return types covering most business scenarios

Improved development efficiency; easy migration from Koa to Umajs

Future Plans

Umajs will further improve its plugin system, add model‑driven development support, and continuously incorporate new technologies based on community feedback.

Contribution & Feedback

Developers are invited to explore the source code at https://github.com/wuba/Umajs , submit PRs or issues, and join the community for direct communication.