README.md 5.87 KB

Kakao

Build status Dependency Status devDependency Status

An API-driven framework for building nodejs apps, using MVC conventions. It only will provide a structure, inspired on Ruby on Rails, that will allow you to organise better your projects, initialise your own or third party libraries, call in a easy way your models, helpers, etc.

Features

  • MVC architecture project
  • ES6 support
  • Helpers support
  • ORM, ODM or DB driver independent
  • Well organized configuration files and routes

TODO

  • Log
    • accessLog
    • requestLog
  • Router
  • REST
    • GET
    • POST
    • PUT
    • DELETE
  • ORM
    • withRelated返回指定的columns - mask plugin
    • 自定义sql
    • schema/joi
    • 分页
    • 使用bookshelf-cascade-delete删除关联表数据,避免使用数据库外键
    • 根据models自动创建CRUD路由
    • insert/update时更新关联表数据
    • joi.description()不起作用
  • Debug
  • HTTPS support
  • Cache
  • Task
  • Test
  • Deploy
  • Daemon
  • Others
    • xx

Installation

First install node.js and mysql. Then:

  1. Clone the project to local

    $ git clone https://github.com/zhongzhi107/kakao
    
  2. Install dependencies

    $ yarn
    
  3. Modify config file config/index.js

    $ vi config/index.js
    
  connection: {
    host: process.env.MYSQL_HOST || 'localhost',
    user: process.env.MYSQL_USER || 'root',
    password: process.env.MYSQL_PASSWORD || '',
    database: process.env.MYSQL_DATABASE || 'kakao',
    port: 3306,
    charset: 'utf8',
    timezone: 'UTC',
    // debug: true,
  }
  1. Migrate data

    $ yarn run migrate:latest
    
  2. Start the application

    $ yarn start
    

    By default the app tries to connect to port 3000. After starting the application you can check it at http://localhost:3000/roles

Convention

以下是默认约定,如果不想按着默认约定编码,可以在代码中使用指定参数的方式更改

  • 数据库、表应该像变量名一样,全部采用小写,但单词之间以下划线分隔,而且表名始终是复数形式的
  • 文件名应该全部小写,单词之间用下划线
  • 关联表名称默认为用下划线连接的被关联的两个表名,且按2个表名称的字母排序先后顺序连接
    • usersposts的关联表名称应该为posts_users
    • tagsposts的关联表名称应该为posts_tags
    • userstags的关联表名称应该为tags_users
  • 关联表名中关联的字段默认为 被关联表名称的单数_id,如 user_id tag_id post_id
  • ...

路由

kakao能根据model自动创建RESTful路由地址

创建一个最简单的CRUD路由

import Role from '../models/roles';
import ResourceRouter from '../utils/router';

export default ResourceRouter.define(Role.collection())

上面的代码会自动创建以下路由:

提交方式 路由 说明
POST /roles 新建一个角色
GET /roles 列出所有角色
GET /roles/:id 获取某个指定角色的信息
PATCH /roles/:id 更新某个指定角色的信息
DELETE /roles/:id 删除某个角色

创建一个嵌套路由

import Role from '../models/role';
import ResourceRouter from '../utils/router';

const users = ResourceRouter.define({
  // 假设在role model中已经设定了role和user的关联关系
  collection: (ctx) => ctx.state.role.users(),
  name: 'users',
  setup(router) {
    router
      .use(async (ctx, next) => {
        ctx.state.role = await Role.findById(
          ctx.params.role_id,
          {require: true}
        );
        await next();
      })
      .crud();
  },
});

export default ResourceRouter.define({
  collection: Role.collection(),
  setup(router) {
    router.crud();
    // router.create().read().update().destroy();

    // 使用嵌套路由
    router.use('/roles/:role_id(\\d+)', users.routes());
  },
});

上面的代码会自动创建以下路由:

提交方式 路由 说明
POST /roles 新建一个角色
GET /roles 列出所有角色
GET /roles/:id 获取某个指定角色的信息
PATCH /roles/:id 更新某个指定角色的信息
DELETE /roles/:id 删除某个指定角色的信息
POST /roles/:role_id/users 新增一个某个指定角色的用户
GET /roles/:role_id/users 列出某个指定角色的所有用户
GET /roles/:role_id/users/:user_id 列出某个指定角色的指定用户
PATCH /roles/:role_id/users/:user_id 修改某个指定角色的指定用户
DELETE /roles/:role_id/users/:user_id 删除某个指定角色的指定用户

API支持的querystring

Overview

...

Notes

  • curl传递多个querystring参数时,& 前需要加 \,如 curl http://localhost/roles?sort=id\&direction=desc
  • curl传递带[]参赛时,需要加上 --globoff 参数,如 curl --globoff http://localhost/roles?where[name]=sales

References