原文地址,向原作者表示感谢。由于本人并没学习过angular,所以翻译有误的地方恳请指正。
我已经受够了JS社区的那帮二货,我只是想使用Django作为后端结合Angular做一个简单的、可复用的项目,却没有一个简明的指导教我如何做到。如果你也为此挣扎,这里有一份指南教你如何构建一个由Django作为后端、Webpack进行组织的Angular程序。
问题
我想开发一个Angular1.1.x的项目并使用Django作为后端提供数据,我喜欢使用Django REST Framework(DRF)来构造RESTful API。我也想打包需要的JavaScript资源。目前,我打算使用单一的服务器上运行这个程序。
依赖
- Python 2.x
- a virtual Python environment
- Django 1.9.x (pip install django)
- npm 2.15.8+
- Webpack 1.13.x (sudo npm i -g webpack)
- ESLint 2.13.1+ (sudo npm i -g eslint)
- NodeJS 4.4.7+
0.设定虚拟环境
mkvirtualenv mysite
在这步,你需要确保安装了上面所有的依赖项,包括Django。
1.创建目录
我们在开发时候就需要聚焦于模块化,因此我们最终会用到许多目录,初始时我们的目录结构如下:
1 |
mysite |
执行:
1 |
mkdir mysite && cd mysite |
注意:这个项目结构的灵感来源几个不同的项目,我认为这个结构是十分理想的,但你并不必须按这种结构组织代码。不过你在跟随文档操作时最好保持这个结构以免出现问题。
2.创建Django项目
进入mysite/backend/
目录创建Django项目:
1 |
python django-admin.py startproject mysite |
并且创建在requirements/
中requirements.txt
文件:
1 |
pip freeze > requirements/requirements.txt |
在mysite/backend/mysite/
目录内创建存放API程序的目录:
1 |
mkdir -p applications/api/v1/ |
接下来创建settings
目录在mysite/backend/mysite/
目录:
1 |
mkdir -p mysite/settings/ |
3.设定Django所需的环境变量
在这步我喜欢使用django-environ
来管理环境变量,当然有很多其他方法来做这件事,不过django-environ
极大的简化了这个过程,所以我在所有的项目中都使用它。
安装
1 |
pip install django-environ |
在mysite/dev.env
中添加:
1 |
DATABASE_URL=sqlite:///mysite.db |
接下来我们将在settings
中使用这些变量,这种在单独文件中配置特定变量的好处就是提供了切换运行环境的简单方法。在这里,dev.env
文件是一个我们在本地开发时候使用的变量列表,同样的prod.env
包含了生产环境所需的变量。
注意:SECRET_KEY
可以在执行django-admin.py startproject
后生成的settings.py
中获取。
4.安装Django REST Framework并配置Django使用环境变量
安装
1 |
pip install djangorestframework |
编写mysite/backend/mysite/settings/base.py
文件:
告诉Django去哪里寻找环境变量
1 |
import environ |
配置数据库,这里我们使用django-environ内置的sqlite配置
1 |
DATABASES = { |
指定SECRET_KEY和DEBUG选项
1 |
SECRET_KEY = env('SECRET_KEY') |
添加DRF到项目中
1 |
# Application definition |
配置URL
1 |
ROOT_URLCONF = 'mysite.urls' |
指定templates和静态资源目录
1 |
STATIC_URL = '/static/' |
根据TEMPLATES
的配置,Django将在frontend/
目录寻找模板文件,这里也是Angular项目存放的位置。我们提供入口指令让Django使用Angular提供的模板。如果你不明白我在说什么,继续往下看……
编写settings/dev.py
:
1 |
from mysite.settings.base import * |
这里我们告诉Django这个配置文件继承自base.py
并且覆盖了CURRENT_ENV
变量,意思就是说“使用这里的变量值而不是base.py中的变量值。”
5.创建API
我们需要数据来测试Angular服务,所以来创建一个简单的API。你可以跳过这一节,但我不建议你这么做。完全的知道Angular的工作设置细节去理解HTTP请求是很重要的。
在mysite/backend/mysite
中创建一个Django App
1 |
mkdir applications/games |
添加games app到settings文件中
1 |
INSTALLED_APPS = [ |
在mysite/backend/mysite/applications/games/models.py
中创建模型
1 |
class (models.model): |
在mysite/backend/mysite/applications/api/v1/serializers.py
中创建serializer
1 |
from rest_framework.serializers import ModelSerializer |
在mysite/backend/mysite/applications/api/v1/viewsets.py
中创建DRF viewset
1 |
from rest_framework import viewsets |
利用DRF的路由注册特性来处理路由信息在mysite/backend/mysite/applications/api/v1/routes.py
中
1 |
from rest_framework import routers |
在mysite/backend/mysite/mysite/urls.py
添加url配置
1 |
from django.contrib import admin |
6.运行Django服务
1 |
manage.py runserver --settings=mysite.settings.dev |
通过DJANGO_SETTINGS_MODULE
我们告诉runserver
命令使用特定的配置文件。
如果一切正常,你可以访问localhost:8000/api/v1/games
并看到DRF的响应,接下来我们开始构建Angular程序。如果你卡住了,在评论区提出你的问题,我将帮助你调试。
7.初始化npm包并安装前端JS依赖项
没正确安装依赖项时Angular程序不会正常工作,这里先安装一些所需的依赖。
初始化NPM包。在mysite/frontend/
目录中执行
1 |
npm init --yes |
通过--yes
参数,告诉NPM命令根据默认选项生成package.json
,这样就不用回答那些无聊的问题了。
安装开发依赖项
1 |
npm install --save-dev eslint eslint-loader |
安装通用依赖项
1 |
npm install --save eslint eslint-loader angular angular-resource angular-route json-loader mustache-loader lodash |
略微调整一下mysite/frontend/
目录中的package.json
文件,如下所示:
1 |
{ |
- eslint - 语法检查器,保持javascript代码的整洁和一致。
- eslint-loader - 通过Webpack运行eslint。我将会稍微解释一下“加载器”的概念。
- angular - MVC框架,如果你不知道这个可以关闭页面了。
- angular-resource - 一款angular的HTTP库,是
$http
的抽象。 - json-loader - 一个加载器(同样的,给Webpack使用),通过
require()
语法来提取.json
文件中的JSON格式内容。 - mustache-loader - 一个加载器,用来解析mustache模板。mustache模板十分有趣。
这里我假定你不知道如何将上面的程序配合使用,别担心老兄。
8.创建Angular程序入口,声明依赖以及全局配置
在mysite/frontend/app/app.js
文件中:
1 |
/* Libs */ |
app.js
是Webpack寻找模块进行打包的入口点,我个人很欣赏这种声明的组织方式和函数调用方式,但这并不是必须的。这里有6部分:
- Libs - 所需要的通用库
- Globals - 所需要的全局变量
- Components - 项目需要的模块
- App Dependencies - 声明程序入口名以及依赖
- Config Vars - 配置变量,比如路由配置
- App Config - 我们程序所需要的变量配置
为了正常使用全局变量,你需要告诉ESLint哪些变量是全局的。编辑mysite/frontend/config/eslint.json
文件:
1 |
{ |
我们告诉ESLint这里有几个全局变量:
_
代表lodash_urlPrefixes
是我们将在程序URL中使用的一个对象,我将晚些解释angular
代表我们的应用中整个AngularJS对象inject
将在Angular依赖注入时使用window
代表JavaScript的window
对象,这里代表了DOM
9.配置Webpack
现在我们已经配置好了项目的依赖关系,可以创建Webpack配置文件了。Webpack将结合我们所依赖的所有文件和我们编写的模块进行打包。
编辑mysite/frontend/webpack.config.js
1 |
module.exports = { |
为了让Webpack能够打包我们的静态依赖文件,我们需要告诉他去哪里获取这些文件、哪些文件需要被处理以及打包前如何管理它们。
让我们概览一下你通过webpack.config.js
告诉Webpack些什么了:
entry
告诉Webpack从什么位置开始构建,这可以是一个绝对路径也可以是一个相对于webpack.config.js
的相对路径。这里我使用后者。output
是一个对象,其中path
表示打包后文件存放的位置,filename
则是文件名,这里我们还使用了sourceMapFilename
来指明什么source map应该被调用。watch
告诉Webpack在它运行时监控文件的变动,如果没设置成true
,Webpack将仅打包一次并退出。eslint
包含ESLint具体的配置,用于eslint-loader
。module
用于告诉Webpack如何处理模块。module.preLoaders
说明在打包前需要做什么,这里我们使用eslint去运行我们的模块。module.loaders
指定加载器的序列,这里我仅设定了test
和loader
。test
表明哪些模块需要运行加载器(通过正则表达式匹配文件名),loader
则表明哪一个加载器将被使用。每个加载器都是字符串并且使用感叹号作为标记,比如loader!another_loader!yet_another_loader
。
但是老兄,preLoaders和loaders又特么的有什么区别??? 我假设你问了这个问题,爱骂人的朋友。
A preLoader 是在加载器运行之前执行的代码,这里我们检查JavaScript语法。
A loader 告诉Webpack如何打包 require() 文件。一个加载器就好象一个模块,说“当你打包这些文件到一个文件时,这些字符串应该如何转换”
A postLoader 是一个Webpack插件在打包完成后运行,为了简单这里我们没指定postLoader。
10.告诉Django加载App
现在,你已经配置了Webpack什么需要创建并如何创建了。(见鬼,此时此刻,如果你运行Webpack命令并且不报错,我会十分惊讶。如果真的成功了,我就是王八蛋。)
自从Django加强了URL管理后,我们常常在Django的摆布下管理用户在本地浏览器中访问的路径。然而我们现在使用另一个框架构建了一个单页面程序,并且希望拥有完全控制用户输入的能力,我们需要的仅仅是Django服务这个单页面程序正常运行。因此……
编辑mysite/backend/mysite/mysite/urls.py
添加下列代码到urlpatterns
中
1 |
# Web App Entry |
这意味着在用户访问mysite.com/
时,env('FRONTEND_ROOT') + app/index.html
将被STATICFILES_FINDERS
找到并渲染成普通HTML模板。
11.创建Angular app模板
我们的mysite/frontend/app/components/app/index.html
看起来就像一个常规的Django模板:
1 |
{% load staticfiles %} |
在此时,你应该能运行Webpack了。如果你运行了Django服务并访问localhost:8000
将会看到一个空白页面。如果没有,请让我知道。
12.写一个home组件
让我们来编写第一个组件,它将在页面上展示文字当用户访问localhost:8000
时。
创建components目录和基本文件在frontend/app/components/
中
1 |
mkdir home && touch home/home-controller.js home/home.js home/home.html |
编辑mysite/frontend/app/components/home/home.html
1 |
<div ng-controller="HomeController as ctrl"> |
接下来编写mysite/frontend/app/components/home/home-controller.js
文件:
1 |
function HomeController() { |
关于var that = this
可以参考另一文章
Angular模块定义应该在home.js
中被声明:
1 |
angular.module("Home", []); |
现在我们可以在定义模块依赖的地方指明”Home”了,让我们动手吧。
编辑mysite/frontend/app/app.js
文件:
1 |
/* Components */ |
13.为home组件和404页面编写路由
现在我们来配置路由,当用户访问localhost:8000
时,Angular应该在Django渲染模板后接手控制。为了实现这一点,我们使用angular-router
。
编辑mysite/frontend/app/routes.js
文件
1 |
function routesConfig($routeProvider) { |
如果我们不添加_urlPrefixes.TEMPLATES
,angular-router将认为components/home/home.html
是一个服务器提供的实际URL路径,因为Django中配置了STATIC_URL
,localhost:8000/components/home/home.html
将不会正常工作。
同样,你应该注意到了otherwise({...})
配置,这是用来控制404页面的。
编辑mysite/frontend/app/404.html
1 |
<h1>NOT FOUND</h1> |
最终在mysite/frontend/app/app.js
添加如下代码
1 |
/* Config Vars */ |
14.在入口页面添加angular-router指令
现在我们需要告诉Angular在用户点击导航时如何切换页面。为了做的这点,我们需要利用angular-router。
在mysite/frontend/app/index.html
的标签中添加下列代码
1 |
<base href="/"> |
在中添加
1 |
<div ng-view></div> |
你的index.html
看起来应该类似这样:
1 |
{% load staticfiles %} |
运行Webpack命令,访问localhost:8000
,你应该看到home/home.html
中的内容了。(如果没有让我知道)
15.结合REST API和Angular app
如果上面的都没问题,现在应该可以为Django API写Angular服务了。让我们来编写一个简单的组件,这个组件用来展示游戏列表,我假设你已经在数据库中添加了数据,访问localhost:8000/api/v1/games
可以得到游戏列表。
在frontend/app/components/
中创建组件
1 |
mkdir -p game/list/ && touch game/list/game-list-controller.js game/list/game-list-controller_test.js game/game-service.js game/game.js game/game.html |
编辑game/game-service.js
1 |
function GameService($resource) { |
注意$resource
的配置,这就是之前设定的HTTP请求的路径。
编辑game/list/game-list-controller.js
1 |
function GameListController(GameService) { |
编辑game/game.html
1 |
<div ng-controller="GameListController as ctrl" ng-init="ctrl.init()"> |
编辑game/game.js
1 |
angular.module("Game", []); |
接下来修改app.js
:
1 |
/* Components */ |
最终,我们还需要游戏列表配置路由,在mysite/frontend/app/routes.js
文件中添加下面的$routeProvider
对象;
1 |
.when("/game", { |
再次运行webpack,所有编译都应该成功,如果没有,请让我知道。
访问localhost:8000/#/games
你将看到游戏列表。
关于非主要部分这里我就不翻译了,各位可以去原博客中评论或提问。