Notoriously Problematic Merge

    coa-http
    TypeScript icon, indicating that this package has built-in type declarations

    0.4.0 • Public • Published

    coa-http

    GitHub license npm version npm downloads PRs Welcome

    English | 简体中文

    A simple, fast, lightweight HTTP service frame, is born for the API.

    Feature

    • For the API Designed for API development, there is no need to consider complex page data rendering logic
    • Lightweight Less than 10K, do not rely on third-party libraries, not encapsulation
    • Flexible Support micro-service, Serverless mode, Context free expansion
    • Document friendship Automatically generate API documents, automatically generate front-end code
    • TypeScript All written in TypeScript, type constraint, IDE friendship
    • Deno Can be supported in Deno (todo)

    Reference

    • Inspired by koa, improve the context generation mechanism
    • Inspired by koa-router, improve the routing generation mechanism
    • Inspired by koa-bodyparser, improve the request body processing mechanism
    • Inspired by egg, improve the context expansion mechanism
    • Based on swagger-ui, complete the automatic generation of interface documents

    Iteration

    • The first version coajs: The first version released in 2019, it belongs to the integration of third-party libraries. From multiple online projects, it is easy to deploy updates as a separate library. With the continuous iteration, there is more and more things, coajs becomes more bloated, is not suitable for lightweight small projects. Iterate 114 times after stop maintenance

    • Second version coa-serve: For the bloated problem of the first release, the various components are split based on coajs, separate the base components and core components into separate libraries, and open source. At the same time, there is a lot of optimization for document generation mechanisms, routing retrieval, system environment configuration. Currently stable, all of my online coajs projects have been migrated to coa-server

    • Third version coa-http: The current version. With the continuous iteration, the way the interface provides service is not limited to http, integrate tcp, websocket, etc. Direct to coa-serve is not elegant. In addition, As the author's cognitive progress, koa ecosystem is not the best choice. Therefore, it is planned to disassemble the coa-serve to reconfigure to coa-http, coa-tcp, coa-websocket, etc. This project coa-http is one of these three, still in the beta stage

    Quick Start

    Environmental install

    Make sure that the latest stable version of Node.js is installed on the operating system

    Create a project

    mkdir <project-name>
    cd <project-name>
    
    yarn add coa-http
    yarn add typescript tsc-watch @types/node -D

    Create files

    gateway            # Gateway layer
    ├─ index.ts        # Gateway entrance
    ├─ debug           # debug module
    │  └─ test.ts      # The route of the debug module
    service            # Service layer
    ├─ index.ts        # Implement service
    package.json
    tsconfig.json

    Write the code in gateway/index.ts

    import { CoaContext, CoaHttp } from 'coa-http'
    
    export const http = new CoaHttp(CoaContext)
    
    http.start().then(() => {
      // Do something after starting
    })

    Write the code in gateway/debug/test.ts

    import { http } from '..'
    
    http.router.register('Debug Something', {
      '/debug/test/hello': {
        options: {
          method: 'GET',
          name: 'Hello, world',
        },
        async handler() {
          return { result: 'hello,world!' }
        },
      },
    })

    Write configuration in tsconfig.json

    {
      "compilerOptions": {
        "strict": true,
        "module": "CommonJS",
        "target": "ESNext",
        "baseUrl": ".",
        "outDir": "node_run",
        "sourceMap": true
      },
      "include": ["gateway", "service"]
    }

    Add dev script of script node in package.json

    {
      "scripts": {
        "dev": "HOST=3000 NODE_PATH=node_run tsc-watch --onSuccess 'node node_run/gateway'"
      }
    }

    Start up

    yarn dev

    See something similar to the following operating results, indicating the success of the program starts. After modifying the code, it will automatically restart the service.

    Found 0 errors. Watching for file changes.
    [server] Booting...
    [server] Startup successful in: 5.399953 ms
    [server] Listening on: http://localhost:3000/gw/doc
    

    At this point, open the http://localhost:3000/gw/doc, you can directly view the interface document.

    Route

    Basic usage

    Use the http.router.register method to register the route, a simplest route as shown below.

    http.router.register('Debug Something', {
      '/debug/test/hello': {
        options: {
          name: 'Test Something', // name
          method: 'GET', // method
          param: {
            title: { required: true, description: 'Title parameters', example: 'test' },
          },
        },
        async handler(ctx) {
          // Get all query parameters
          const query = ctx.request.query
          // Get title parameters
          const title2 = ctx.get('title')
          // Return the result with JSON format
          return { query, title }
        },
      },
    })

    Route group

    Each of the registered routes will be automatically divided into a group. When developing, you can split each module into a file separate grouping.

    // gateway/module-a.ts
    http.router.register('Module A', {
      '/api/module-a/action-1': {
        /* ... */
      },
      '/api/module-a/action-2': {
        /* ... */
      },
    })
    // gateway/module-b.ts
    http.router.register('Module B', {
      '/api/module-b/action-1': {
        /* ... */
      },
      '/api/module-b/action-2': {
        /* ... */
      },
      '/api/module-b/action-3': {
        /* ... */
      },
    })

    Context

    Similar to koa, handler method contains a ctx parameter. ctx is an instance of Context that contains all the above information during the current request.

    http.router.register('Debug Something', {
      '/debug/test/hello': {
        options: {
          method: 'GET',
          name: 'Hello, world',
        },
        async handler(ctx) {
          // ctx contains all context information
          return { result: 'hello, world!' }
        },
      },
    })

    Custom response format

    coa-http Natively supports the response results in json and text format. But sometimes we need to customize the response format, such as a stream format. The following example shows the returns of resources on the network through the stream.

    http.router.register('Debug Something', {
      '/debug/test/proxy': {
        options: {
          method: 'GET',
          name: 'Returns the result with stream',
          param: {
            url: { required: true, description: 'Network resource path', example: 'http://github.com' },
          },
        },
        async handler(ctx) {
          // Get url parameters
          const url = ctx.required('url', '')
    
          // Get resource streams on the network
          const { data, status, headers } = await axios.get(url, { responseType: 'stream' }).catch((e) => e.response)
    
          // Set response info
          ctx.res.statusCode = status
          ctx.res.setHeader('Content-Type', headers['content-type'])
    
          // Resource flow on the network flows in the pipeline
          data.pipe(ctx.res)
    
          // Custom response results, coa-http will not perform subsequent response processing
          return ctx.custom()
        },
      },
    })

    Install

    npm i coa-http

    DownloadsWeekly Downloads

    28

    Version

    0.4.0

    License

    MIT

    Unpacked Size

    60.3 kB

    Total Files

    26

    Last publish

    Collaborators

    • adaex