kites.js

/ home / Documentation / Templates

Templates

Kites là một dự án mã nguồn mở với mục tiêu là tạo ra các ứng dụng Web dựa trên các bản mẫu một cách nhanh chóng và dễ dàng.

Do đó, trước khi bạn có thể khởi tạo được một loạt các ứng dụng bạn cần phải cài đặt @kites/cli trước đã:

npm install -g @kites/cli

Yêu cầu tối thiểu

Kites yêu cầu trước đó bạn đã cài đặt, phiên bản thấp hơn sẽ không được hỗ trợ:

  • Nodejs >= 6.9.1
  • NPM >= 3.8.10

Mọi thắc mắc, lỗi xảy ra trong quá trình phát triển bạn có thể tạo issue ở đây:

MVC Template

Kites MVC là template dựng sẵn tuân thủ theo mẫu kiến trúc phần mềm Model - View - Controller (MVC). Điều này có nghĩa là việc sử dụng Kites MVC sẽ giúp bạn có thể tạo ra được các ứng dụng trở nên đơn giản hơn đối với các dự án có nhiều nghiệp vụ phức tạp.

Kiến trúc mô hình MVC

mvc model

MVC là một kiến trúc phần mềm hay mô hình thiết kế được sử dụng trong kỹ thuật phần mềm. Thực chất, mô hình này sẽ phân bố source code thành 3 phần, mỗi thành phần có một nhiệm vụ riêng biệt và độc lập với các thành phần khác (như hình).

Khi có một yêu cầu từ phía client gửi đến server, bộ phận controller có nhiệm vụ nhận yêu cầu, xử lý yêu cầu đó. Và nếu cần, nó sẽ gọi đến phần model, vốn là bộ phần làm việc với Database. Sau khi xử lý xong, toàn bộ kết quả được đẩy về phần View. Tại View, sẽ biên dịch ra mã Html tạo nên giao diện, và trả toàn bộ html về trình duyệt để hiển thị.

Kites Service

Kites bổ sung thêm tầng Service nằm bên dưới kiến trúc MVC, nhằm mục đích tạo ra các nghiệp vụ logic nhiều bước quy trình, thực hiện các tác vụ của ứng dụng, nơi trung chuyển dữ liệu dữ các hệ thống và (hoặc) truy xuất tới các đối tượng dữ liệu từ nhiều nguồn khác nhau, như: Database, File, Web service, Network, Sub system …

Từ trên xuống dưới thì kiến trúc của Kites-MVC được thể hiện theo thứ tự như sau:

Xây dựng một ứng dụng Kites MVC?

#1. Khởi tạo dự án của bạn

Sau khi cài đặt @kites/cli thì bạn có thể khởi tạo dự án của mình bằng các lệnh sau:

# khởi tạo dự án
kites init my-project --template mvc

# di chuyển vào thư mục dự án
cd my-project

# cài đặt các phụ thuộc và công cụ build
npm install

# chạy lệnh sau đây để xem thành quả tại http://localhost:3000
npm start

#2. Phát triển và bảo trì dự án MVC

# chạy ở chế độ phát triển
npm run dev

Bố cục của dự án được tổ chức như hình sau đây.

kites mvc

#3. Thiết lập cấu hình

Lưu ý: Thiết lập cấu hình kết nối cho kites trong file kites.config.json

Dưới đây là nội dung các cấu hình được thiết lập mặc định, bạn hoàn toàn có thể thay đổi nó cho dự án của mình.

{
    "extensionsLocationCache": true,
    "logger": {
        "console": {
            "transport": "console",
            "level": "info"
        }
    },
    "extensions": null,
    "kites-api": {
        "connection": "memory",
        "dataSource": [{
            "name": "memory",
            "driver": "memory",
            "active": true
        }, {
            "name": "mysql",
            "driver": "mysql",
            "host": "localhost",
            "port": "3306",
            "username": "root",
            "password": "",
            "database": "test",
            "active": false,
            "pool": true
        }]
    },
    "express": {
        "static": "./public",
        "httpPort": 3000,
        "poweredBy": "Kites",
        "views": {
            "engine": "ejs",
            "path": "content/views"
        }
    }
}

ApiDoc Template

ApiDoc hay tài liệu hướng dẫn sử dụng API là một nội dung kỹ thuật có thể phân phối hoặc dùng để tham chiếu, bao gồm những hướng dẫn sử dụng và tích hợp API một cách hiệu quả.

Tại sao tài liệu API lại quan trọng?

Một vài gạch đầu dòng cho biết ApiDoc rất quan trọng:

Tài liệu hướng dẫn sử dụng API thường được khởi tạo (1) và bảo trì (2) bằng cách soạn thảo văn bản thông thường hoặc theo chuẩn mở OpenAPI/Swagger Sepecification, sau đó bạn hoàn toàn có thể đưa lên Web Online (3). Trong phạm vi của kites framework thì kites sẽ hỗ trợ bạn tạo ra một trang tài liệu tĩnh được dùng để mô tả và hướng dẫn lập trình tích hợp với API của bạn hiệu quả như trang demo này.

Cách tạo ApiDoc với kites như thế nào?

#1. Khởi tạo dự án của bạn

Sau khi cài đặt @kites/cli thì bạn có thể khởi tạo dự án của mình bằng các lệnh sau:

# khởi tạo dự án
kites init my-project --template apidoc

# di chuyển vào thư mục dự án
cd my-project

# cài đặt các phụ thuộc và công cụ build
npm install

# build trang tài liệu mà bạn đã viết bằng markdown
npm run build

# chạy lệnh sau đây để xem thành quả tại http://localhost:3000
npm start

#2. Phát triển và bảo trì dự án ApiDoc

Rõ ràng tài liệu của bạn sẽ thay đổi khi có cập nhật và nâng cấp. Theo đó, thì bạn cũng cần cập nhật nội dung tài liệu ApiDoc của mình trong thư mục source/includes. Để nhìn thấy kết quả luôn trong quá trình sửa đổi tài liệu, chạy lệnh:

# chạy ở chế độ phát triển tài liệu
npm run dev

Chú ý: Nếu cần thiết thay đổi thứ tự xuất hiện của tài liệu, hãy sửa đổi nội dung file index.yml, mục includes như hình sau đây.

apidoc

#3. Đưa tài liệu lên Web Online

Sau khi tài liệu đã được build bạn hoàn toàn có thể đưa trang tài liệu của mình lên Web Online, bằng 1 trong 3 phương án sau đây.

Phương án 1: Bạn có vps hoặc máy chủ riêng, bạn chỉ cần up code và chạy lệnh

# tại thư mục của dự án
npm start

Phương án 2: Đưa lên heroku

Deploy

Phương án 3: Đưa lên Github Pages

Bạn hãy dùng git để đưa trang tài liệu của mình lên Github, ý tưởng là bạn có thể lưu trang tài liệu của trên nhánh gh-pages hoặc sử dụng thư mục docs trên nhánh master.

Để cho đơn giản mình chọn thư mục docs trên nhánh master, các bạn có thể thao tác với git bằng các lệnh sau đây.

# tại thư mục của dự án
git init
git remote add origin [email protected]:your-user-name/your-kites-apidoc.git

# build lại dự án trước khi publish
npm run build

# add toàn bộ source code
git add .
git commit -m "init api document"

# add tài liệu đã được build ra
git add -f docs/*
git commit -m "update document"

git push origin master

Chatbot Template