|
1 |
| -Node ES6 REST Template |
2 |
| -====================== |
3 |
| -The purpose of this template is to kick-start your Node.js projects using ES6. It implements best practices in developing RESTful APIs and Domain-Driven Design. Features include: |
4 |
| -- Use of the [Hexagonal Architecture](http://alistair.cockburn.us/Hexagonal+architecture) to arrange the application into logical layers, with well-defined responsibilities. |
5 |
| -- Use of BDD and [Specification-by-Example](http://specificationbyexample.com/) techniques for documenting application features. [Yadda](https://github.com/acuminous/yadda) is used for automated testing. |
6 |
| -- RESTful APIs are implemented using the [Express](http://expressjs.com/) framework. |
7 |
| -- Persistence is implemented using an in-memory repository layer. This can be substituted with any persistence technology of your choice. |
8 |
| -- Logging and error handling are implemented using [Bunyan](https://github.com/trentm/node-bunyan). |
9 |
| - |
10 |
| -Requirements |
11 |
| ------------- |
12 |
| -- Install Node |
13 |
| - - on OSX, install [home brew](http://brew.sh/) and type `brew install node` |
14 |
| - - on Windows, use the installer available at [nodejs.org](http://nodejs.org/) |
| 1 | +# Node ES6 REST Template |
15 | 2 |
|
16 |
| -- Clone this repo |
17 |
| - |
18 |
| -- Open a terminal (command line) window |
| 3 | +The purpose of this template is to kick-start your Node.js projects using ES6. It implements best practices in developing RESTful APIs and Domain-Driven Design. Features include: |
19 | 4 |
|
20 |
| -- Type `npm install -g node-inspector node-gyp gulp bunyan` |
21 |
| - - node-gyp is required for `npm install` to succeed |
22 |
| - - bunyan is required for displaying the application log in a human readable format |
| 5 | +- Use of the [Hexagonal Architecture](http://alistair.cockburn.us/Hexagonal+architecture) to arrange the application into logical layers, with well-defined responsibilities. |
| 6 | +- RESTful APIs are implemented using the [Express](http://expressjs.com/) framework. |
| 7 | +- Persistence is implemented using an in-memory repository layer. This can be substituted with any persistence technology of your choice. |
23 | 8 |
|
24 |
| -Getting started (Dev Mode) |
25 |
| --------------------------- |
26 |
| -First make a copy of the sample environment file `.env-sample` to `.env`. Make any environment changes only in this copy. The `.env` file may vary for different environments (development, test, prod etc.) and should not be checked in to the repository. |
| 9 | +## Dev Build |
27 | 10 |
|
28 |
| -To run the application in development mode: |
29 | 11 | ```bash
|
30 | 12 | $ npm install
|
31 |
| -$ npm run watch |
| 13 | +$ npm start |
32 | 14 | ```
|
33 | 15 |
|
34 |
| -- `npm install` will install the required node libraries under `node_modules`. This needs to be run only once. |
35 |
| -- `npm run watch` will start the application. It is designed for an efficient development process. As you make changes to the code, the application will restart to reflect the changes immediately. Also, Node.js is started with the `--inspect` flag so that debugging is turned on. |
36 |
| - |
37 |
| -To verify that the application is working correctly, point your browser to [http://localhost:8080/v1/accounts](http://localhost:8080/v1/accounts) - you should see a response with a list of accounts in JSON format. Since the persistence layer is in memory, the list will be empty. |
38 |
| - |
39 |
| -Running Lint |
40 |
| ------------- |
41 |
| -To run ESLint on the `src` folder: |
42 |
| - |
43 |
| - $ npm run lint |
44 |
| - |
45 |
| -To run ESLint on the `test` folder: |
46 |
| - |
47 |
| - $ npm run lint:test |
48 |
| - |
49 |
| -Testing the application |
50 |
| ------------------------ |
51 |
| -- Make sure the server is running. |
52 |
| -- In another shell, run acceptance tests using the following command |
53 |
| - |
54 |
| -```bash |
55 |
| -$ npm test |
56 |
| -``` |
| 16 | +To verify that the application is working correctly, point your browser to [http://localhost:8080/api/books](http://localhost:8080/api/books) - you should see a response with a list of books in JSON format. |
57 | 17 |
|
58 |
| -Building for production |
59 |
| ------------------------ |
60 |
| -When you want to deploy the application into production, run the following command: |
| 18 | +## Production Build |
61 | 19 |
|
62 | 20 | ```bash
|
63 | 21 | $ npm run build
|
64 |
| -$ npm start |
| 22 | +$ npm serve |
65 | 23 | ```
|
66 | 24 |
|
67 |
| -- `npm run build` compiles the ES6 code into the dist directory. This needs to be run only once. |
68 |
| -- `npm start` runs the application from the dist directory. |
69 |
| - |
70 |
| -You can also substitute the following command instead of `npm start` to avoid a dependency on npm: |
71 |
| - |
72 |
| - node dist/index.js | bunyan -o short |
73 |
| - |
74 |
| -Folder Structure |
75 |
| ----------------- |
76 |
| - |
77 |
| -### Highest Level Structure |
78 |
| - |
79 |
| -``` |
80 |
| -/node_modules |
81 |
| -/src |
82 |
| -/dist |
83 |
| -/test |
84 |
| -``` |
85 |
| - |
86 |
| -- `node_modules:` Node.js modules downloaded by `npm install` (do not check in) |
87 |
| -- `src:` contains all the ES6 source files for the RESTful server |
88 |
| -- `dist:` contains the compiled version ready for distribution (do not check in) |
89 |
| -- `test:` server tests |
90 |
| - |
91 |
| -### Source Folder Structure |
| 25 | +## Folder Structure |
92 | 26 |
|
93 | 27 | ```
|
94 | 28 | /src
|
95 | 29 | /adapters
|
96 |
| - /app |
97 |
| - /core |
| 30 | + /services |
| 31 | + /repositories |
98 | 32 | ```
|
99 | 33 |
|
100 |
| -The server folder contains sub-folders that arrange the application into logical layers as suggested by the [Hexagonal Architecture](http://alistair.cockburn.us/Hexagonal+architecture) (a.k.a. the [Onion Architecture](http://jeffreypalermo.com/blog/the-onion-architecture-part-1/)): |
101 |
| - |
102 |
| -- The `adapter` layer *adapts* interactions from the external world to the application layer. This layer contains REST adapters as well as database repositories that allow the application layer to interact with the external world. Note that we are using in-memory persistence in the repositories. These can be easily modified to persist to a relational or NoSQL database. |
| 34 | +The source folder contains sub-folders that arrange the application into logical layers as suggested by the [Hexagonal Architecture](http://alistair.cockburn.us/Hexagonal+architecture) (a.k.a. the [Onion Architecture](http://jeffreypalermo.com/blog/the-onion-architecture-part-1/)): |
103 | 35 |
|
104 |
| -- The `application` layer coordinates high-level activities such as creation of the domain objects and asking them to perform tasks requested by the external world. |
| 36 | +- The `adapter` layer _adapts_ interactions from the external world to the service layer. This layer contains REST adapters. |
105 | 37 |
|
106 |
| -- The `core` layer contains common application facilities such as logging and database initialization. |
| 38 | +- The `service` layer coordinates high-level activities such as creation of domain objects and asking them to perform tasks requested by the external world. It interacts with the repository layer to save and restore objects. |
107 | 39 |
|
| 40 | +- The `repository` layer is responsible for persisting domain objects and performing CRUD operations on them. Note that this implementation uses in-memory persistence but it can be easily modified to use a relational or NoSQL database for persistence. |
0 commit comments