mirror of
https://github.com/Hopiu/angular.js.git
synced 2026-03-17 07:40:22 +00:00
304 lines
No EOL
13 KiB
Text
304 lines
No EOL
13 KiB
Text
@workInProgress
|
||
@ngdoc overview
|
||
@name Developer Guide: Dependency Injection
|
||
@description
|
||
Dependency injection (DI) is one of the core design patterns in angular and angular applications. DI
|
||
allows you to replace almost any part of angular framework or angular application with a custom
|
||
implementation, allowing for a highly flexible, maintainable and testable code-base.
|
||
|
||
Dependency injection is a very common pattern in Java and other statically typed languages. While
|
||
undervalued among JavaScript developers, we feel strongly that DI in JavaScript allows us to achieve
|
||
the same benefits as in other languages.
|
||
|
||
This document will focus on using dependency injection in angular. It is outside of the scope of
|
||
this document to explain details of dependency injection. For more information on this topic, please
|
||
refer to these links:
|
||
|
||
* {@link http://en.wikipedia.org/wiki/Dependency_injection DI - Wikipedia}
|
||
* {@link http://martinfowler.com/articles/injection.html Inversion of Control by Martin Fowler}
|
||
* Java
|
||
* {@link http://code.google.com/p/google-guice/ Guice}
|
||
* {@link http://www.devshed.com/c/a/Java/The-Spring-Framework-Understanding-IoC/ Spring}
|
||
* {@link http://picocontainer.org/injection.html picoContainer}
|
||
* .NET
|
||
* {@link http://msdn.microsoft.com/en-us/magazine/cc163739.aspx MSDN Design Patterns - Dependency Inject}
|
||
* {@link http://www.springframework.net/ Spring.NET}
|
||
|
||
|
||
|
||
# Dependency Injection in angular
|
||
|
||
Angular's dependency injection story begins with a `service`. Service in angular lingo is a
|
||
JavaScript object, function, or value that is created by angular's injector via a provided factory
|
||
function. The factory function is registered with angular via {@link angular.service}.
|
||
|
||
<pre>
|
||
// register a factory for a uniqueId service.
|
||
angular.service('uniqueId', function(){
|
||
// calling the factory function creates the instance function
|
||
var id = 0;
|
||
return function(){
|
||
// calling the counter instance function will return and increment the count
|
||
return ++id;
|
||
}
|
||
});
|
||
</pre>
|
||
|
||
At run-time we can access the `uniqueId` service by looking it up with the service locator like
|
||
this:
|
||
|
||
<pre>
|
||
// create new root scope which has the injector function `$service()`
|
||
var scope = angular.scope();
|
||
|
||
// use the `$service` function to look up the service instance function
|
||
var idGenerator = scope.$service('uniqueId');
|
||
expect(idGenerator()).toBe(1);
|
||
|
||
// subsequent lookups using the same root scope return the service instance
|
||
var idGenerator2 = scope.$service('uniqueId');
|
||
expect(idGenerator).toBe(idGenerator2);
|
||
|
||
// since it is same instance calling idGenerator2 returns 2;
|
||
expect(idGenerator2()).toBe(2);
|
||
</pre>
|
||
|
||
The {@link angular.service service} registry seems like a lot of work, so what are the benefits? To
|
||
answer this question, it’s important to realize that in large scale applications there are a lot of
|
||
services which are often dependent on each other, as in this example:
|
||
|
||
<pre>
|
||
angular.service('gadgetFactory', function(uniqueId){
|
||
return function(){
|
||
return {gadgetId: uniqueId()};
|
||
};
|
||
}, {$inject: ['uniqueId']});
|
||
</pre>
|
||
|
||
Specifically, notice that the `gadgetFactory` takes `uniqueId` service in its arguments. It also
|
||
declares this dependency with the `$inject` property. There are several benefits to this approach:
|
||
|
||
* There is no need for a `main` method for an application responsible for instantiating and wiring
|
||
these services. The order of service instantiation and wiring can be inferred by examining the
|
||
`$inject` annotations.
|
||
* It is easy to replace any one service with a different implementation without having to track down
|
||
all of the dependencies. This is useful in:
|
||
* Tests: when mocks of services are needed (for example using mock {@link angular.service.$xhr}.)
|
||
* Customization: when the service bundled with angular does not do exactly what the application
|
||
requires.
|
||
|
||
More importantly, as we'll soon learn, controllers and other components of angular applications can
|
||
also declare their dependencies on services and these will be provided without explicitly looking
|
||
them up, but let's not get ahead of ourselves.
|
||
|
||
Lastly, it is important to realize that all angular services are singletons – application singletons
|
||
to be more precise. This means that there is only one instance of a given service per injector. And
|
||
since angular is lethally allergic to the global state, it's absolutely possible to create multiple
|
||
injectors each with its own instance of a given service (but that is not typically needed, except in
|
||
tests where this property is crucially important).
|
||
|
||
|
||
## Service Locator and Scope
|
||
|
||
The {@link angular.injector injector} is responsible for resolving the service dependencies in the
|
||
application. It gets created and configured with the creation of a root scope in your application.
|
||
The injector is responsible for caching the instances of services, but this cache is bound to the
|
||
scope. This means that different root scopes will have different instances of the injector. While
|
||
typical angular applications will only have one root scope (and hence the services will act like
|
||
application singletons), in tests it is important to not share singletons across test invocations
|
||
for isolation reasons. We get this isolation by having each test create its own separate root scope.
|
||
|
||
<pre>
|
||
// crate a root scope
|
||
var rootScope = angular.scope();
|
||
// accesss the service loctor
|
||
var myService = rootScope.$service('myService');
|
||
</pre>
|
||
|
||
|
||
|
||
# Dependency Injection in Controllers
|
||
|
||
So far we have been talking about injector as a service locator. This is because we have been
|
||
explicitly calling the `$service` method to gain access to the service. Service locator is not
|
||
dependency injection since the caller is still responsible for retrieving the dependencies. *True
|
||
dependency injection is like Chuck Norris. Chuck does not ask for dependencies; he declares them.*
|
||
|
||
The most common place to use dependency injection in angular applications is in
|
||
{@link angular.ng:controller controllers}. Here’s a simple example:
|
||
|
||
<pre>
|
||
function MyController($route){
|
||
// configure the route service
|
||
$route.when(...);
|
||
}
|
||
MyController.$inject = ['$route'];
|
||
</pre>
|
||
|
||
In this example, the `MyController` constructor function takes one argument, the
|
||
(@link angular.service.$route $route) service. Angular is then responsible for supplying the
|
||
instance of `$route` to the controller when the constructor is instantiated. There are two ways to
|
||
cause controller instantiation – by configuring routes with the $route service or by referencing the
|
||
controller from the HTML template, such as:
|
||
|
||
<pre>
|
||
<!doctype html>
|
||
<html xmlns:ng="http://angularjs.org" ng:controller="MyController">
|
||
<script src="http://code.angularjs.org/angular.min.js" ng:autobind></script>
|
||
<body>
|
||
...
|
||
</body>
|
||
</html>
|
||
</pre>
|
||
|
||
When angular is instantiating your controller, it needs to know what services, if any, should be
|
||
injected (passed in as arguments) into the controller. Since there is no reflection in JavaScript,
|
||
we have to supply this information to angular in the form of an additional property on the
|
||
controller constructor function called `$inject`. Think of it as annotations for JavaScript.
|
||
|
||
<pre>
|
||
MyController.$inject = ['$route'];
|
||
</pre>
|
||
|
||
The information in `$inject` is then used by the {@link angular.injector injector} to call the
|
||
function with the correct arguments.
|
||
|
||
|
||
|
||
# Using Dependency Injection pragmatically
|
||
|
||
At times you’ll need to use dependency injection pragmatically, usually when instantiating
|
||
controllers manually or writing unit tests. This section explains how to go about it.
|
||
|
||
## Retrieving Services
|
||
|
||
The simplest form of dependency injection is manual retrieval of scopes, known as service locator.
|
||
We say manual because we are asking the injector for an instance of the service (rather then having
|
||
the injector provide them to the function). This should be rare since most of the time the dependent
|
||
services should be injected into the controller using the `$inject` property array.
|
||
|
||
<pre>
|
||
// create a root scope. The root scope will automatically have
|
||
// `$service` method defined which is configured with all services.
|
||
// Each instance of root scope will have separate instances of services.
|
||
var rootScope = angular.scope();
|
||
|
||
// ask for a service explicitly
|
||
var $window = rootScope.$service('$window');
|
||
</pre>
|
||
|
||
|
||
## Creating Controllers using Dependency Injection
|
||
|
||
In a typical angular application the dependency injection is most commonly used when creating
|
||
controllers.
|
||
<pre>
|
||
// declare our own service by registering a factory function.
|
||
angular.service('counter', function(){
|
||
var count = 0;
|
||
return function(){ return count++; };
|
||
});
|
||
|
||
// example of a controller which depends on '$window' and 'counter' service
|
||
// notice that there is an extra unbound parameter 'name' which will not
|
||
// be injected and must be supplied by the caller.
|
||
function MyController($window, counter, name) {
|
||
}
|
||
|
||
// we must declare the dependencies explicitly and in the same order as in
|
||
// the constructor function. This information is used by the dependency
|
||
// injection to supply the arguments.
|
||
// Notice the lack of 'name' argument which makes it an unbound argument.
|
||
MyController.$inject = ['$window', 'counter'];
|
||
|
||
|
||
// Create a root scope which creates the the injector
|
||
var rootScope = angular.scope();
|
||
|
||
// use the '$new()' method instead of standard 'new' keyword operator to
|
||
// create an instance of MyController and have the dependency injection
|
||
// supply the arguments to the controller. The dependency injection only
|
||
// supplies the bound arguments in `$inject` all addition arguments are
|
||
// curried from the '$new', in our case 'Alexandria' is the argument which
|
||
// will be curried to the 'name' argument, while '$window' and 'counter'
|
||
// are supplied by the dependency injection.
|
||
var myController = rootScope.$new(MyController, 'Alexandria');
|
||
// NOTE: the returning controller will be a child scope of parent scope,
|
||
// in this case the root scope.
|
||
</pre>
|
||
|
||
|
||
## Calling functions and Curring of arguments
|
||
|
||
NOTE: this section is quite lame. The concept it is trying to describe is more closely related to
|
||
scope#new than scope#$service. We need a better example to discuss here. Ideally a parent controller
|
||
creating a child controller imperatively via $new where the child controller's constructor function
|
||
declares a portion of its dependencies via $inject property, but another portion is supplied by the
|
||
caller of $new (e.g. parentCtrl.$new(ChildCtrl, configParam1, configParam2);
|
||
|
||
Finally, you may need to call functions but have the `$inject` properties of the function be
|
||
supplied by the injector.
|
||
|
||
<pre>
|
||
// create a root scope with the `$service` injector.
|
||
var rootScope = angular.scope();
|
||
|
||
// given a function such as
|
||
function greet ($window, name) {
|
||
$window.alert(this.salutation + ' ' + name);
|
||
}
|
||
greet.$inject = ['$window'];
|
||
|
||
// you can call function 'greet' such that the injector supplies the
|
||
// '$window' and the caller supplies the function 'this' and the 'name'
|
||
// argument.
|
||
var fnThis = {salutation: 'Hello'}
|
||
rootScope.$service(greet, fnThis, 'world');
|
||
</pre>
|
||
|
||
|
||
|
||
# Inferring `$inject`
|
||
|
||
** EXPERIMENTAL: this is an experimental feature, see the important note at the end of this section
|
||
for drawbacks. **
|
||
|
||
We resort to `$inject` and our own annotation because there is no way in JavaScript to get a list of
|
||
arguments. Or is there? It turns out that calling `.toString()` on a function returns the function
|
||
declaration along with the argument names as shown below:
|
||
|
||
<pre>
|
||
function myFn(a,b){}
|
||
expect(myFn.toString()).toEqual('function myFn(a,b){}');
|
||
</pre>
|
||
|
||
This means that angular can infer the function names after all and use that information to generate
|
||
the `$inject` annotation automatically. Therefore the following two function definitions are
|
||
equivalent:
|
||
|
||
<pre>
|
||
// given a user defined service
|
||
angular.service('serviceA', ...);
|
||
|
||
// inject '$window', 'serviceA', curry 'name';
|
||
function fnA($window, serviceA, name){};
|
||
fnA.$inject = ['$window', 'serviceA'];
|
||
|
||
// inject '$window', 'serviceA', curry 'name';
|
||
function fnB($window, serviceA_, name){};
|
||
// implies: fnA.$inject = ['$window', 'serviceA'];
|
||
</pre>
|
||
|
||
If angular does not find an `$inject` annotation on the function, then it calls the `.toString()`
|
||
and tries to infer what should be injected using the following rules:
|
||
|
||
* any argument starting with `$` is angular service and will be added to `$inject` property array.
|
||
* any argument ending with `_` will be added to the `$inject` property array but we strip the `_`
|
||
* all arguments following an argument which has neither `$` nor `_` , must not have `$` nor `_`
|
||
(these are free arguments for {@link http://en.wikipedia.org/wiki/Currying curring})
|
||
|
||
**IMPORTANT**
|
||
Minifiers/obfuscators change the names of function arguments and will therefore break the `$inject`
|
||
inference. For this reason, either explicitly declare the `$inject` or do not use
|
||
minifiers/obfuscators. In the future, we may provide a pre-processor which will scan the source code
|
||
and insert the `$inject` into the source code so that it can be minified/obfuscated. |