This is an automated email from the ASF dual-hosted git repository.
iluo pushed a commit to branch asf-site
in repository https://gitbox.apache.org/repos/asf/incubator-dubbo-website.git
The following commit(s) were added to refs/heads/asf-site by this push:
new 29e5ddc Translate Design Principals (#310)
29e5ddc is described below
commit 29e5ddc08f1ed55c7a23f388172cc5ad4182424b
Author: Jlcao <[email protected]>
AuthorDate: Tue Apr 16 10:39:36 2019 +0800
Translate Design Principals (#310)
* Add english version for Design Principles
fixes #196
* Translate code-detail.md
* Translate introduction.md
* Translate dummy.md
* Update configuration.md
Translate configuration.md
* Translate expansibility.md
Translate expansibility.md
* Translate extension.md
Translate extension.md
* Translate general-knowledge.md
Translate general-knowledge.md
* Update general-knowledge.md
* Translate robustness.md
Translate robustness.md
* Translate ‘向后兼容性，可以多向HTML5学习，参见：[HTML5设计原理]’.
Translate ‘向后兼容性，可以多向HTML5学习，参见：[HTML5设计原理]’.
* Update expansibility.md
There are more and more products in our platform >> Our platform products
more and more.
* see here => refer to
see here => refer to
* Update robustness.md
* Update robustness.md
Translate ' 这样操作减少后，保证数据库可以冷却（Cool Down）下来。'
* Update configuration.md
---
docs/en-us/dev/principals/code-detail.md | 36 +++++
docs/en-us/dev/principals/configuration.md | 83 ++++++++++
docs/en-us/dev/principals/dummy.md | 203 +++++++++++++++++++++++++
docs/en-us/dev/principals/expansibility.md | 18 +++
docs/en-us/dev/principals/extension.md | 135 ++++++++++++++++
docs/en-us/dev/principals/general-knowledge.md | 68 +++++++++
docs/en-us/dev/principals/introduction.md | 3 +
docs/en-us/dev/principals/robustness.md | 83 ++++++++++
8 files changed, 629 insertions(+)
diff --git a/docs/en-us/dev/principals/code-detail.md
b/docs/en-us/dev/principals/code-detail.md
new file mode 100644
index 0000000..57ebc23
--- /dev/null
+++ b/docs/en-us/dev/principals/code-detail.md
@@ -0,0 +1,36 @@
+# The devil is in the details
+
+> http://javatar.iteye.com/blog/1056664
+
+Recently, I have been worried about the quality of the Dubbo distributed
service framework. If there are more maintenance personnel or changes, there
will be a decline in quality. I am thinking, is there any need for everyone to
abide by it, according to a habit when writing code, I have summarized it. The
code process, especially the framework code, should always keep in mind the
details. Maybe the following will be said, everyone will feel very simple, very
basic, but always keep in mi [...]
+
+## Prevent null pointer dereference and index out of bounds
+
+This is the exception I least like to see, especially in the core framework,
in contrast I would like to see a parameter not legal exception with detail
information. This is also a robust program developer who should be prevented in
the subconscious by writing every line of code. Basically, you must be able to
ensure that the code that is written once will not appear in the case of no
test.
+
+## Ensure thread safety and visibility
+
+For framework developers, a deep understanding of thread safety and visibility
is the most basic requirement. Developers are required to ensure that they are
correct in the subconscious when writing each line of code. Because of this
kind of code, it will look normal when doing functional tests under small
concurrency. However, under high concurrency, there will be inexplicable
problems, and the scene is difficult to reproduce, and it is extremely
difficult to check.
+
+## Fail fast and precondition
+
+Fail fast should also become a subconscious mind, assert at the entrance when
there are incoming parameters and state changes. An illegal value and state
should be reported at the first time, rather than waiting until the time is
needed. Because when it is time to use, other related states may have been
modified before, and few people in the program handle the rollback logic. After
this error, the internal state may be confusing, and it is easy to cause the
program to be unrecoverable on [...]
+
+## Separate reliable operation and unreliable operation
+
+The reliability here is narrowly defined whether it will throw an exception or
cause a state inconsistency. For example, writing a thread-safe Map can be
considered reliable, but writing to a database can be considered unreliable.
Developers must pay attention to its reliability when writing each line of
code, divide it as much as possible in the code, and handle exceptions for
failures, and provide clear logic for fault-tolerant, self-protection,
automatic recovery or switching. The ent [...]
+
+## Safeguard against exceptions, but does not ignore exceptions
+
+The exception defense mentioned here refers to the maximum tolerance of the
code on the non-crucial path, including the bug on the program. For example,
the version number of program is retrieved by scanning the Manifest and jar
package names. This logic is auxiliary, but the code is quite a bit. Although
the initial test works well but you should add a try-catch block to cover the
whole getVersion() function, if something goes wrong then print error message
and return the basic version. [...]
+
+## Reduce scope of variable and use final liberally
+
+If a class can be an Immutable Class, it is preferred to design it as an
Immutable Class. The immutable class has natural concurrency advantages, reduce
synchronization and replication, it can efficiently help analyze the scope of
thread safety. Even if a mutable class, for references passed in from
constructor then held internally, it is better to make this field final, so as
not to be mistakenly modified. Don't assume that the field won't be reassigned
if this field is private or this [...]
+
+## Reduce misunderstanding when modifying, do not bury mine
+
+It is repeatedly mentioned that the code being modified by the others, and
this is something developers should keep in mind. This other person includes
the future of yourself, you always have to think about this code, someone may
change it. I should give the modified person a hint, let him know my current
design intent, instead of adding hidden rules in the program, or bury some
easily overlooked mines, such as: use null to indicate that it is not
available, the size is equal to 0 means [...]
+
+## Improve code testability
+The testability here mainly refers to the ease of Mock and the isolation of
the test cases. As for the automation, repeatability, stability, disorder,
completeness (full coverage), lightweight (fast execution) of the test, the
general developer, plus the assist of tools such as JUnit can do it. Can also
understand its benefits, just the matter of workload. Primary emphasis on
unicity(only test the target class itself) and isolation(do not propagate
failure). Nowadays there is too much em [...]
diff --git a/docs/en-us/dev/principals/configuration.md
b/docs/en-us/dev/principals/configuration.md
new file mode 100644
index 0000000..be11a81
--- /dev/null
+++ b/docs/en-us/dev/principals/configuration.md
@@ -0,0 +1,83 @@
+# The configuration design
+
+> http://javatar.iteye.com/blog/949527
+
+Dubbo design is now completely unobtrusive, namely the user only depends on
the configuration of contract.After multiple versions of the development, in
order to meet the demand of various scenarios, configuration is more and
more.In order to maintain compatibility with only grow, lurking inside all
sorts of styles, convention, rules.The new version will also be configured for
a adjustment, remove the dubbo, properties, instead of all the spring
configuration.Will think of some written i [...]
+
+## Classification of configuration
+
+First of all, the purpose is to have a variety of configuration, which can be
roughly divided into:
+
+0. Environment configuration, such as: the number of connections, the timeout
configuration, etc.
+0. Describe the configuration, such as: service interface description, service
version, etc.
+0. Extension configuration, such as: protocol extension, strategy to expand,
etc.
+
+## Configuration format
+
+Usually environment configuration, using the configuration properties will be
more convenient, because is some simple discrete values, with the key - value
configuration can reduce the learning cost configuration.
+
+Describe the configuration, information more often, and even have a hierarchy,
using XML configuration would be more convenient, because the tree structure
configuration expression was stronger.If very complex, and can also custom DSL
as configuration.Sometimes such configuration can also use the Annotation
instead of, because the configuration and related business logic, in the code
is also reasonable.
+
+Another extension configuration, which may be different.If only policy
interface implementation class to replace, can consider the properties of the
structure.If there is a complex life cycle management, may need to configure
such as XML.Sometimes extended by registering interface provided.
+
+## Configuration is loaded
+
+For environment configuration, in the Java world, comparing to conventional
approach, was agreed in a project under the classpath for the name of the
configuration properties, such as: log4j. Properties, velocity. The properties
and so on.Product during initialization, automatically from the classpath under
loading the configuration.Our platform of many programs use a similar strategy,
such as: dubbo. Properties, comsat. XML, etc.This has its advantages, is based
on agreement, simplifies [...]
+
+Dubbo new version removes `dubbo.properties`, because the contract often
conflicts configuration.
+
+And to describe the configuration, because want to participate in the business
logic, usually embedded into the application of life cycle management.There are
more and more using spring projects, directly using the spring configuration is
common, and spring permits custom schema, configuration simplified is very
convenient.Also has its disadvantages, of course, is strongly dependent on the
spring, can ask programming interface to do the matching scheme
+
+In Dubbo configuration is described, but also environment configuration.Part
with spring schame configuration is loaded, in part, from the classpath
scanning properties configuration is loaded.Users feel very inconvenient, so in
the new version of the merged, unified into spring schame configuration load,
also increases the flexibility of configuration.
+
+Extension configuration, usually to the configuration of aggregate demand is
higher.Because the product need to find the third party implementation, add it
to the product inside.Agreed in the Java world, usually in a specified file
each jar package down load, such as: the eclipse plugin. The XML, struts 2
struts - plugin. XML, and so on, this kind of configuration can consider Java
standard service discovery mechanisms, namely in the jar meta-inf/services
placed under the interface class [...]
+
+Dubbo old version under each jar package through agreement, place called Dubbo
- context. The spring configuration XML extensions and integration, the new
version to use the JDK's own meta-inf/services, spring from too much dependence.
+
+## Programmable configuration
+
+Configuration of programmability is very necessary, no matter in what way you
load the configuration file, should provide a programming way of configuration,
allows the user to not using a configuration file, complete the configuration
process with code directly.As a product, especially the component products,
usually require collaboration use and other products, when a user integration
of your product, may need adapter configuration mode.
+
+Dubbo new version offers one-on-one configuration class with XML
configuration, such as: ServiceConfig corresponding ` < Dubbo: service / > `,
and one-to-one attributes, this configuration file configuration and
programming the consistency of the understanding, reduce the learning cost.
+
+## Configure the default
+
+Configuration of the default, usually set the reasonable value of a regular
environment, thus reducing the user's configuration.Is generally recommended
that in online environment for reference, the development environment can adapt
by changing the configuration.The default Settings, had better be in the
outermost configuration do processing load.The underlying program if found
configuration is not correct, you should direct error, fault tolerance in the
outermost layer.If, when the unde [...]
+
+## Configuration consistency
+
+Configuration is always implied some style or hidden rules, should as far as
possible to keep its consistency.For example: a lot of functions have switch,
and then have a configuration value：
+
+0. Whether to use the registry, the registry address.
+0. Whether to allow a retry, retries.
+
+You may agree:
+
+0. Each is to configure a Boolean type of switch, to configure a value.
+0. On behalf of the closed with an invalid values, N/A address 0 retries, etc.
+
+No matter which way, all the configuration items, should keep the same style,
Dubbo selected is the second.Also, similar to that of timeout, retry time,
timer interval.If a unit is second, another unit is milliseconds (C3P0
configuration item is) so, staff will be crazy.
+
+## Configuration coverage
+
+Provide configuration, want to consider developers, testers, piping, the
system administrator.Testers can't modify the code, and test environment is
likely to be more complex, need to have some set aside for testers "back door",
can be modified in the peripheral configuration items.Like spring is
accomplished configuration, support ` SYSTEM_PROPERTIES_MODE_OVERRIDE `, can
through the JVM -d parameters, or like hosts agreed a cover configuration
files, on the outside of the program, modif [...]
+
+
+Dubbo support through the JVM parameter ` - Dcom. XXX. XxxService = Dubbo: / /
10.1.1.1:1234` directly make the remote service call bypass registry, point to
point test.There is a kind of situation, developers to increase the
configuration, can according to the deployment of online configuration, such
as: ` < dubbo: registry address = "${dubbo. Registry. Address}" / > ` because
only one online registry, this configuration is no problem, and the testing
environment may have two registry, [...]
+`<dubbo:registry address="${dubbo.registry.address1}" />`，
+`<dubbo:registry address="${dubbo.registry.address2}" />`，So this place, Dubbo
support in the ${Dubbo. Registry. Address} value, through vertical dividing
multiple registry addresses, used to represent a registry address.
+
+## Configuration inheritance
+
+Configuration is also "duplicate code", there is also a "generalization and
elaboration" problem.Such as: Dubbo timeout Settings, each service, and each
method, should be can set the timeout.But a lot of service don't care about
overtime, if required each method configuration, it is not realistic.So Dubbo
adopted method inherit service timeout, overtime service timeout to inherit the
default timeout, no configuration, opens up search.
+
+Dubbo, moreover, the old version all the timeout, retries, load balancing
strategies are only in the service consumer configuration.But in the process of
actual use, found that the service provider knows better than consumer, but the
configuration items are used in consumer.The new version, joined in the
provider can match these parameters, through the registry to the consumer,As a
reference, if there is no configuration, consumer to provide configuration
shall prevail, the equivalent of [...]
+Dubbo, moreover, the old version all the timeout, retries, load balancing
strategies are only in the service consumer configuration.But in the process of
actual use, found that the service provider knows better than consumer, but the
configuration items are used in consumer.The new version, joined in the
provider can match these parameters, through the registry to the consumer.
+
+
+
+## Configuration backward compatibility
+
+Forwards compatibility is very good, as long as you guarantee configuration
only grow, basically can guarantee forwards compatibility.But backward
compatibility, but also should pay attention to, to prepare for subsequent to
join the new configuration items.If a special configuration in configuration,
you should make an appointment a compatibility for the "special" case rules,
because the special case, probably will happen later.For example, have a
configuration file is save "service = a [...]
+
+Backward compatibility, can learn a lot from HTML5, refer to：[HTML5 design
principle](http://javatar.iteye.com/blog/949390)
diff --git a/docs/en-us/dev/principals/dummy.md
b/docs/en-us/dev/principals/dummy.md
new file mode 100644
index 0000000..0b73930
--- /dev/null
+++ b/docs/en-us/dev/principals/dummy.md
@@ -0,0 +1,203 @@
+# "Fool-proof" design
+
+> http://javatar.iteye.com/blog/804187
+
+Recently I was feeling stupid because I solved too many stupid problems. The
service framework is becoming more widely used. Every day, I have to help the
endpoint user to resolve problems. Gradually, it is found that most of the
problems are configuration errors, or duplicated files or classes, or network
failure. So I prepare to add some "fool-proof" design to the further version.
It may be very simple, but it is still a little help for troubleshooting speed.
I hope that I can throw a [...]
+
+## Check for duplicated jars
+
+The most annoying problem is that, if we have several jars with different
version number at the same time, there will be a problem. Imagine that, a new
version of the Class A may invoke a old version of the Class B, it's related to
the JVM loading order. The problem may encounter occasionally and hard to
resolve. So the first, let's try to avoid it. For each jar package, pick a
class that will be loaded, check it for duplication for example:
+
+```java
+static {
+ Duplicate.checkDuplicate(Xxx.class);
+}
+```
+
+Utility class for check duplication：
+
+```java
+public final class Duplicate {
+
+ private Duplicate() {}
+
+ public static void checkDuplicate(Class cls) {
+ checkDuplicate(cls.getName().replace('.', '/') + ".class");
+ }
+
+ public static void checkDuplicate(String path) {
+ try {
+ // search from ClassPath
+ Enumeration urls =
Thread.currentThread().getContextClassLoader().getResources(path);
+ Set files = new HashSet();
+ while (urls.hasMoreElements()) {
+ URL url = urls.nextElement();
+ if (url != null) {
+ String file = url.getFile();
+ if (file != null && file.length() > 0) {
+ files.add(file);
+ }
+ }
+ }
+ // if there are more than one indicates duplication
+ if (files.size() > 1) {
+ logger.error("Duplicate class " + path + " in " + files.size()
+ " jar " + files);
+ }
+ } catch (Throwable e) { // safe guard
+ logger.error(e.getMessage(), e);
+ }
+ }
+
+}
+```
+
+## Check for duplicate configuration files
+
+It is also a frequently encountered problem that the configuration file is
loaded incorrectly. Users often complain that they have the right configuration
but program says something is wrong. After some troubleshooting, found that the
configuration file is not even loaded. Many products put a default
configuration file under classpath, if there are several, usually the first one
loaded by JVM is effective. In order not to be bothered by such problem, just
like checking duplicate jars, add this:
+
+```java
+Duplicate.checkDuplicate("xxx.properties");
+```
+
+## Check for optional configuration
+
+The required configuration is estimated to be checked by everyone, because
without it the program may not even start. However, for some optional
parameters, some checks should also be made. For example, the service framework
allows the service consumers and service providers to be associated with the
registry, and allows direct configuring the service provider address to
point-to-point direct connect. At this time, the registry address is optional,
but if there is no point-to-point direc [...]
+
+## Provide error message with a solution if possible
+
+It's hard to troubleshooting problem with a simple error message which has no
detail information. For example, the last time I encountered a "Failed to get
session" exception, just the few words. I'm wondering which session is wrong?
What is the reason Failed? It makes me crazy, the problem happens in an
production environment and it's hard to reproduce. The exception should have
some basic context information, such as author info, operation system, failed
reason. The best exception info [...]
+
+## And also the environment information
+
+Every time an application error occurs, the developer or QA will send the
error message and ask the reason. At this time, I will ask some question again,
which version is used? Is it a production environment or a development
environment? Which registry center? Which project is it? Which machine? And
which service? The problem is, some developers or QA can't tell the difference,
it waste me a lot of time. So, it is best to log some environment information,
we can make a wrapper. Decorate [...]
+
+```java
+public void error(String msg, Throwable e) {
+ delegate.error(msg + " on server " + InetAddress.getLocalHost() + " using
version " + Version.getVersion(), e);
+}
+```
+
+Utility class for retrieve version：
+
+```java
+public final class Version {
+
+ private Version() {}
+
+ private static final Logger logger =
LoggerFactory.getLogger(Version.class);
+
+ private static final Pattern VERSION_PATTERN =
Pattern.compile("([0-9][0-9\\.\\-]*)\\.jar");
+
+ private static final String VERSION = getVersion(Version.class, "2.0.0");
+
+ public static String getVersion(){
+ return VERSION;
+ }
+
+ public static String getVersion(Class cls, String defaultVersion) {
+ try {
+ // search version number from MANIFEST.MF
+ String version = cls.getPackage().getImplementationVersion();
+ if (version == null || version.length() == 0) {
+ version = cls.getPackage().getSpecificationVersion();
+ }
+ if (version == null || version.length() == 0) {
+ // if not found, extract from jar name
+ String file =
cls.getProtectionDomain().getCodeSource().getLocation().getFile();
+ if (file != null && file.length() > 0 &&
file.endsWith(".jar")) {
+ Matcher matcher = VERSION_PATTERN.matcher(file);
+ while (matcher.find() && matcher.groupCount() >
0) {
+ version = matcher.group(1);
+ }
+ }
+ }
+ // return version, return default if null
+ return version == null || version.length() == 0 ? defaultVersion :
version;
+ } catch (Throwable e) {
+ // ignore exception, return default version
+ logger.error(e.getMessage(), e);
+ return defaultVersion;
+ }
+ }
+
+}
+```
+
+## Dump before kill
+
+Every time there is a problem with the production environment, everyone
panics. Usually the most direct way is to rollback and restart, to reduce the
downtime. So that the scene is destroyed, and it's hard to check the problem
afterwards. Some problem is hard to reproduce in development environment and
may happen under hard pressure. It is unlikely let the developer or Appops
manually backup all the data before. Therefore, it is best to call dump before
the kill script to backup automati [...]
+
+```sh
+JAVA_HOME=/usr/java
+OUTPUT_HOME=~/output
+DEPLOY_HOME=`dirname $0`
+HOST_NAME=`hostname`
+
+DUMP_PIDS=`ps --no-heading -C java -f --width 1000 | grep "$DEPLOY_HOME" |awk
'{print $2}'`
+if [ -z "$DUMP_PIDS" ]; then
+ echo "The server $HOST_NAME is not started!"
+ exit 1;
+fi
+
+DUMP_ROOT=$OUTPUT_HOME/dump
+if [ ! -d $DUMP_ROOT ]; then
+ mkdir $DUMP_ROOT
+fi
+
+DUMP_DATE=`date +%Y%m%d%H%M%S`
+DUMP_DIR=$DUMP_ROOT/dump-$DUMP_DATE
+if [ ! -d $DUMP_DIR ]; then
+ mkdir $DUMP_DIR
+fi
+
+echo -e "Dumping the server $HOST_NAME ...\c"
+for PID in $DUMP_PIDS ; do
+ $JAVA_HOME/bin/jstack $PID > $DUMP_DIR/jstack-$PID.dump 2>&1
+ echo -e ".\c"
+ $JAVA_HOME/bin/jinfo $PID > $DUMP_DIR/jinfo-$PID.dump 2>&1
+ echo -e ".\c"
+ $JAVA_HOME/bin/jstat -gcutil $PID > $DUMP_DIR/jstat-gcutil-$PID.dump 2>&1
+ echo -e ".\c"
+ $JAVA_HOME/bin/jstat -gccapacity $PID >
$DUMP_DIR/jstat-gccapacity-$PID.dump 2>&1
+ echo -e ".\c"
+ $JAVA_HOME/bin/jmap $PID > $DUMP_DIR/jmap-$PID.dump 2>&1
+ echo -e ".\c"
+ $JAVA_HOME/bin/jmap -heap $PID > $DUMP_DIR/jmap-heap-$PID.dump 2>&1
+ echo -e ".\c"
+ $JAVA_HOME/bin/jmap -histo $PID > $DUMP_DIR/jmap-histo-$PID.dump 2>&1
+ echo -e ".\c"
+ if [ -r /usr/sbin/lsof ]; then
+ /usr/sbin/lsof -p $PID > $DUMP_DIR/lsof-$PID.dump
+ echo -e ".\c"
+ fi
+done
+if [ -r /usr/bin/sar ]; then
+/usr/bin/sar > $DUMP_DIR/sar.dump
+echo -e ".\c"
+fi
+if [ -r /usr/bin/uptime ]; then
+/usr/bin/uptime > $DUMP_DIR/uptime.dump
+echo -e ".\c"
+fi
+if [ -r /usr/bin/free ]; then
+/usr/bin/free -t > $DUMP_DIR/free.dump
+echo -e ".\c"
+fi
+if [ -r /usr/bin/vmstat ]; then
+/usr/bin/vmstat > $DUMP_DIR/vmstat.dump
+echo -e ".\c"
+fi
+if [ -r /usr/bin/mpstat ]; then
+/usr/bin/mpstat > $DUMP_DIR/mpstat.dump
+echo -e ".\c"
+fi
+if [ -r /usr/bin/iostat ]; then
+/usr/bin/iostat > $DUMP_DIR/iostat.dump
+echo -e ".\c"
+fi
+if [ -r /bin/netstat ]; then
+/bin/netstat > $DUMP_DIR/netstat.dump
+echo -e ".\c"
+fi
+echo "OK!"
+```
diff --git a/docs/en-us/dev/principals/expansibility.md
b/docs/en-us/dev/principals/expansibility.md
new file mode 100644
index 0000000..3526a67
--- /dev/null
+++ b/docs/en-us/dev/principals/expansibility.md
@@ -0,0 +1,18 @@
+# Talk about expansion of extension and incremental extension
+
+> http://javatar.iteye.com/blog/690845
+
+
+There are more and more products in our platform, the function of the product
also more and more.Platform products in order to meet the requirement of each
BU and department as well as product line, will surely will be a lot of
irrelevant function together, the customer can use selective.In order to
compatible with more demand for each product, each framework, are constantly
expanding, and we often choose some extension of the extension, namely to old
and new function expanded into a gen [...]
+
+Such as: remote invocation framework, definitely not serialize function,
function is very simple, is to transfer as object, the object into a stream.But
because of some places may be using osgi, such serialization, IO in this may be
isolated and the business side of this.Need to stream into byte [] array, and
then passed on to the business side of this serialization.In order to adapt
itself to the requirements of the osgi, expanded the original non osgi with
osgi scenes, so, no matter wh [...]
+
+Such as: remote invocation framework, definitely not serialize function,
function is very simple, is to transfer as object, the object into a stream.But
because of some places may be using osgi, such serialization, IO in this may be
isolated and the business side of this.Need to stream into byte [] array, and
then passed on to the business side of this serialization.In order to adapt
itself to the requirements of the osgi, expanded the original non osgi with
osgi scenes, so, no matter wh [...]
+
+Such as: no status messages before, is very simple, just pass a serialized
object.Later a synchronous message send demand, need a Request/Response
matching, using extended extension, naturally thought, stateless news is
actually a Request without Response, add a Boolean state so in the Request,
said do you want to return the Response.If the message is sent to a Session
needs again, then add a Session interaction, and then found that the original
synchronous message sent is a special case [...]
+
+
+
+If the incremental extension, stateless messages intact, synchronous message
is sent, on the basis of stateless news add a Request/Response processing,
message sending session, plus a SessionRequest/SessionResponse processing.
+
+
diff --git a/docs/en-us/dev/principals/extension.md
b/docs/en-us/dev/principals/extension.md
new file mode 100644
index 0000000..8d1560d
--- /dev/null
+++ b/docs/en-us/dev/principals/extension.md
@@ -0,0 +1,135 @@
+# Extension points to reconstruct
+
+> http://javatar.iteye.com/blog/1041832
+
+With the promotion of service, the website of Dubbo service framework
requirements gradually increase, Dubbo existing developers can implement demand
is limited, many requirements have been delay, and site classmates also want to
participate, combined with field, so the platform will be open to internal part
of the project, let everyone together to implement, Dubbo as one of the pilot
project.
+
+Now that want to open it, about to take some extension point Dubbo, let
participants black box extend as far as possible, rather than a white box to
modify the code, or branch, quality, merger, the conflict will be hard to
manage.
+
+First look at the Dubbo existing design：
+
+
+
+There though some extension interface, but not very good collaboration, and
loading and configuration of extension points are not unified handling, so face
it under the refactoring.
+
+## Step 1, the core plug-in, equal treatment to the third party
+
+Now that want to expand, extension point loading mode, the first thing to
unification, micro core + plug-in, can achieve the principle of OCP is train of
thought.
+
+Made up of a plugin lifecycle management container, core, core does not
include any functions, this will ensure that all functions can be replaced, and
framework, the authors can achieve the function of the extension must also can
do it, so as to guarantee the equal treatment to a third party, so, the
function of the framework itself also want to use the plug-in way, cannot have
any hard coded.
+
+Micro core usually adopt the Factory, the IoC, the OSGi plugin lifecycle
management.Consider the applicable Dubbo, strong don't want to rely on the
Spring IoC container.The IoC container that you made a small also feel a little
too much design, so intend to use the most simple way of Factory management
plug-in.
+
+Finally decided to adopt the JDK standard SPI extension mechanism, see: `
Java. Util. The ServiceLoader `, namely extension in the jar package `
meta-inf/services / ` directory placed with interface of text files, with the
same content for interface implementation class name, multiple separate
implementation class name with a newline.Need to expand Dubbo agreement, for
example, simply by XXX. Placed in a jar file: ` meta-inf/services/com. Alibaba.
Dubbo. RPC. Protocol `, contents for ` c [...]
+
+All plug-in and agreed, must be marked with: ` @ the Extension ` (" name "),
as the identity of the name, after loading is used to configure option.
+
+## Step 2 each extension point encapsulate a change factor, only to maximize
reuse
+
+Each extension point implementers, usually only care about one thing, now the
extension points, is not entirely separate.Such as: Failover, the Route,
LoadBalance, Directory not completely separate, all written by
RoutingInvokerGroup died.
+
+Again, for example, protocol extension, the extension may just want to replace
the serialization way, or just replace transmission mode, and Remoting and Http
can also reuse serialization, etc.In this way, the need for transport, the
client, the server implementation, protocol parsing, data serialization, allow
different extension point.
+
+After break up, the design is as follows:
+
+
+
+
+## Step 3, the entire pipeline design, logic framework itself, are implemented
using cross section intercept
+
+Now a lot of logic, are placed in the base class implementation, then by the
method of template back to the realization of the tone categories, including:
local, mock, generic, echo, token, accesslog, monitor, count, limit, etc., can
use the Filter to realize all split, each function is called a ring on the
chain.Such as: (the base class template method)
+
+```java
+public abstract AbstractInvoker implements Invoker {
+
+ public Result invoke(Invocation inv) throws RpcException {
+ // Pseudo code
+ active ++;
+ if (active > max)
+ wait();
+
+ doInvoke(inv);
+
+ active --;
+ notify();
+ }
+
+ protected abstract Result doInvoke(Invocation inv) throws RpcException
+
+}
+```
+
+To: (chain filter)
+
+```java
+public abstract LimitFilter implements Filter {
+
+ public Result invoke(Invoker chain, Invocation inv) throws RpcException {
+ // Pseudo code
+ active ++;
+ if (active > max)
+ wait();
+
+ chain.invoke(inv);
+
+ active --;
+ notify();
+ }
+
+}
+```
+
+## Step 4, a minimum concept, consistent conceptual model
+
+Keep the concept of as little as possible, help to understand, for open
systems is particularly important.In addition, the interface can use a
consistent conceptual model, can guide each other, and reduce the model
transformation,
+
+For example, Invoker method signature as follows:
+
+```java
+Result invoke(Invocation invocation) throws RpcException;
+```
+
+The Exporter method signature as follows:
+
+```java
+Object invoke(Method method, Object[] args) throws Throwable;
+```
+
+But they are the same, only is a on the client side, one on the server side,
different model classes are applied.
+
+For example, the URL string, parse and assembled, not a URL model classes, and
the Parameters of the URL, but sometimes the Map, and sometimes the Parameters
class wrapping,
+
+```java
+export(String url)
+createExporter(String host, int port, Parameters params);
+```
+
+Use consistent model:
+
+```java
+export(URL url)
+createExporter(URL url);
+```
+
+For example, the existing: Invoker, Exporter, InvocationHandler,
FilterChainAre actually invoke behavior at different stages, can abstract away
completely, unified for the Invoker, reduce the concept.
+
+## Step 5, hierarchical, modular extensions, rather than generic type extension
+
+Why see:[expansibility](../principals/expansibility.md)。
+
+Generalization expansion refers to: the extension point gradually abstraction,
take all functions, sets and new function is always set in and expand the
function of the old concept.
+
+Combined extension refers to: the extension points orthogonal decomposition,
all functions of overlap, new function is always based on the old function
implementation.
+
+The above design, unconsciously will Dubbo existing function as the core
functionality.Above contains the concept of Dubbo existing RPC all functions,
including: the Proxy, the Router, Failover, LoadBalance, Subscriber, Publisher,
Invoker, Exporter, Filter, etc.,
+But these are the core?RPC can Run, kicked off what?And what is not kick
off?Based on this consideration, the RPC can be broken down into two levels,
Protocol and Invoker is the core of RPC.Other, including the Router, Failover,
Loadbalance, Subscriber, the Publisher is the core, but the Routing.Therefore,
the Routing as an extension of the Rpc core, design is as follows:
+
+
+
+## Step 6, and networking
+
+After finishing, the design is as follows:
+
+
+
+
diff --git a/docs/en-us/dev/principals/general-knowledge.md
b/docs/en-us/dev/principals/general-knowledge.md
new file mode 100644
index 0000000..b958a13
--- /dev/null
+++ b/docs/en-us/dev/principals/general-knowledge.md
@@ -0,0 +1,68 @@
+# Some in the design of the basic common sense
+
+> http://javatar.iteye.com/blog/706098
+
+Recently told the new team some design on the common sense, is likely to be
new and some other help, the thought of a few temporarily, first write here.
+
+## The API and SPI separation
+
+Framework or component there are generally two types of customers, one is a
consumer, is an extension.API (Application Programming Interface) is used to
users, and SPI (Service dojo.provide Interface) is used to expand.At design
time, try to put them off, and don't mix.In other words, the user is can't see
write the implementation of the extension.
+
+For example, a Web framework, it has an API interface to call the Action,
there is a the execute () method, which is for the user to write business
logic.Then, Web frameworks have a SPI interface to extend the control output,
such as velocity templates output or a json output, etc.If this Web framework
using an inheritance VelocityAction and a JsonAction as extension of the
Action, with output velocity templates will inherit VelocityAction, want to use
the json output will inherit JsonAc [...]
+
+
+
+
+Is a reasonable way, there is a separate Renderer interface, VelocityRenderer
and JsonRenderer implementation, Web framework will transfer the output of the
Action to the Renderer interface for rendering output.
+
+
+
+
+## Service domain/entity/session domains separation
+
+Any framework or component, there will always be the core domain model, such
as: Spring Bean, Struts Action, Service of Dubbo, Napoli Queue, and so on.The
core areas of the model and its component is called physical domain, it
represents our goal to operate on itself.Physical domain is thread-safe,
usually either through the same class, sync, or copy the way.
+
+Service domain, that is, behavior domain, it is the function of the
components, but also is responsible for the entity and session domains of life
cycle management, such as Spring ApplicationContext, Dubbo ServiceManager,
etc.Service domain objects often is heavy, and is thread-safe, and serve all
calls to a single instance.
+
+What is a session?Is an interactive process.Session key is the concept of
context, the context is what?For example, we said: "old place", the "old place"
is the context information.Why do you say "old place" other person will know,
because we defined earlier the specific content of the "old place".So, the
context often hold state variables in the process of interaction, etc.The
session object, were generally mild and every request to create an instance,
destroyed after the request.In sho [...]
+
+
+
+
+## On the important process to interceptor interface
+
+If you want to write a remote invocation framework, the remote call block the
process should have a unified interface.If you want to write an ORM framework,
that at least the SQL execution, the Mapping process to intercept interface;If
you want to write a Web framework, the request execution should be interception
interfaces, and so on.No common framework can Cover all requirements, allowing
external behavior, is the basic extension of the framework.Before a remote
call, so that if someo [...]
+
+
+
+## The important status of sending events and set aside to monitor interface
+
+Here to tell the difference between an event and the interceptor above, the
interceptor is in the process of intervention, it is part of the process, is
based on process behavior, and event is based on state data, any behavior
changes of the same condition, the event should be consistent.Event is usually
after the event notification is a Callback interface, the method name is
usually past tense, such as onChanged ().Remote invocation framework, for
example, when the network disconnect or [...]
+
+
+
+## Extension interface functions as a single, composability
+
+For example, the remote invocation framework agreement is to replace it.If
only provide a general extension interface, switch can deal, of course, but the
protocol support can be subdivided into the underlying communication,
serialization, dynamic proxy mode and so on.If the interface split, orthogonal
decomposition, will be easier to reuse existing logical extension, and just
replace a part of the implementation strategy.Of course the decomposition the
granularity of the need to grasp.
+
+## Micronucleus plug-in, equal treatment to the third party
+
+"A good framework of development, abide by the concept of micronucleus.Eclipse
is OSGi microkernel, Spring's microkernel is the BeanFactory, Maven microkernel
is breadth.With functional core is usually should not be, but a life cycle and
integrated container, so that each function can interact through the same way
and extension, and any function can be replaced.If they do not microkernel,
must be at least equal treatment to a third party, namely, the author can
realize the function of ex [...]
+
+## Don't control the external object lifecycle
+
+Such as the above said the Action using the interface and the Renderer
extension interface.Framework if let users or extend the Action or the Renderer
implementation class name of the class or kind of meta information submitted,
then internally by reflecting newInstance () to create an instance of this
framework is to control the Action or the Renderer implementation class life
cycle, the Action or the Renderer physical, frameworks do it himself, external
extension or integration are pow [...]
+
+## Configurable must be programmable, and maintain friendly CoC conventions
+
+Framework using the environment uncertainty because of the many, there will
always be some configuration, usually to a specified name classpath straight
sweep configuration, or startup allows you to specify the configuration path.As
a common framework, should do all can do configuration file must be able to
programmatically, or when the user needs to be your frame with another frame
integration will bring a lot of unnecessary trouble.
+
+In addition, as far as possible do a standard contract, if the user has to do
things by some sort of agreement, there is no need for the configuration
items.Such as: configuration templates location, you can agree, if in the
templates directory doesn't have to match, if you want to change the directory,
and configuration.
+
+## Distinguish between commands and queries, clear pre-conditions and
post-conditions
+
+This is part of the design by contract, try to keep to a return value method
is to query methods, void return method is to command.Query methods are usually
idempotence, without side effects, also is not change any state, the n results
are the same, such as the get a property value, or query a database
record.Command is to point to have side effects, namely will change state, such
as set a value, or update a database record.If you have modified the status of
the operation, do a query ret [...]
+
+## Incremental extension, and not to extend the original core concept
+
+refer to：[expansibility](./principals/expansibility.md)
diff --git a/docs/en-us/dev/principals/introduction.md
b/docs/en-us/dev/principals/introduction.md
new file mode 100644
index 0000000..9a7c042
--- /dev/null
+++ b/docs/en-us/dev/principals/introduction.md
@@ -0,0 +1,3 @@
+# Design principals
+
+The design principles in this chapter are taken from a series of articles
published by Liang Fei on javaeye.
\ No newline at end of file
diff --git a/docs/en-us/dev/principals/robustness.md
b/docs/en-us/dev/principals/robustness.md
new file mode 100644
index 0000000..1726e88
--- /dev/null
+++ b/docs/en-us/dev/principals/robustness.md
@@ -0,0 +1,83 @@
+# The robustness of the design implementation
+
+> http://oldratlee.com/380/tech/java/robustness-of-implement.html
+
+
+Dubbo as a remote service exposure, calls and management solutions, through
the meridians of the application is running, its itself to achieve robustness
of importance is self-evident.
+
+Here are some Dubbo principle and method of use.
+
+## The log
+
+Logging is one of the most commonly used way to find, discover problems.Log
quality is often neglected, there is no log on using expressly agreed
upon.Attaches great importance to the use of the Log, and improve the
concentration of the Log information.Log too much, too much chaos, could lead
to useful information.
+
+To effectively use this tool to note:
+
+### Record the contents of the stipulated strictly WARN, the ERROR level
+
+* WARN that can restore the problem without human intervention.
+* The ERROR says requires human intervention.
+
+With such agreement, the regulatory system found in the ERROR log file of the
string will call the police, and to minimize the occurrence.Excessive alarm can
let a person tired, make the person lose vigilance in alarm, make the ERROR
log.Along with artificial, regularly check the WARN level information to assess
the degree of "subhealth" system.
+
+### In the log, as much as possible to collect key information
+
+What is the key information?
+
+* Site information at the time of the problem, namely the screening questions
to use information.Such as service invocation fails, to give the use of Dubbo
version, the service provider's IP, which is used in the registry;Which service
invocation, which method and so on.This information if not given, then later
artificial collection, problem after the site may have already can't recover,
increase the difficulty of the problem.
+* If possible, the cause of the problem and the solution is given.This makes
maintenance and problem solving becomes simple, rather than seeking savvy
(often the implementer) for help.
+
+### Don't duplicate records many times the same or a class of problems
+
+The same or a kind of abnormal log continuous there dozens of times, still can
often see.The human eye is easy to miss under the different important log
information.Try to avoid this situation.Will appear in the foreseeable, it is
necessary to add some logic to avoid.
+
+As a symbol for a question, a problem after log Settings after sign and avoid
a repeat of the log.The problem clear sign after recovery.
+
+Although a bit troublesome, but do ensure log information concentration, the
more effective for monitoring.
+
+## Limit set
+
+Resources are limited, CPU, memory, IO, etc.Don't cry because it is outside of
the request, the data is not limited.
+
+### The size of the thread pool (ExectorService) and saturated strategy
+
+The Server end ExectorService set limit for processing requests.Use limited
queue ExecutorService task waiting queue, avoid resource depletion.When the
task waiting queue saturated, choose a suitable saturated strategy.This ensures
smooth degradation.
+
+In Dubbo, saturated strategy is to discard data, waiting for the result is
only a request timeout.
+
+Saturated, the specification has reached the maximum load, the service
provider to logging in the operation of the saturated strategy of the problem,
in order to monitor warnings.Remember to be careful not to repeat many times
record well.(note that the default saturation strategy will not have these
additional operation.)According to the frequency of the alarm, has decided to
increase adjustment, etc., avoid system problems are ignored.
+
+### The collection capacity
+
+If to ensure element is controlled on the collection and is small enough, then
you can rest assured use.This is most of the situation.If can't guarantee
anything, use a bounded set.When reach the boundary, choose a suitable strategy.
+
+## Fault tolerant - retry - recovery
+
+High availability components to tolerate its dependence on the failure of the
component.
+
+### Dubbo service registry
+
+The service registry using the database to store the information service
providers and consumers.Different registry registry cluster through the
database to synchronize data, to perceive other providers on the
registry.Registry would ensure a provider and consumer data in memory, the
database is unavailable, independent of the normal operation of foreign
registry, just can't get other registry data.When the database recovery, retry
logic will modify memory write data back to the database [...]
+
+### Service consumers
+
+After the message service provider list from the registry, will save the
provider list to memory and disk file.Consumers can function properly after
this registry is down, even in the registry during outage restart
consumers.Consumers started, find the registry is not available, will read the
list stored in the disk file provider.Retry logic to ensure the registry after
recovery, update the information.
+
+## Retry delay strategy
+
+On a bit of the subproblem.Dubbo encountered two related scenario.
+
+### On the database lock
+
+Registration center will regularly update the database of a record timestamp,
such cluster other registry perceive it is alive.Overdue registry and its
associated data will be cleared.Database is normal, the mechanism as well.But
the database load is high, its every action is slow.This occurs:
+
+A registry that B expired, delete B data.B find their data, to write their own
data repeatedly.These repeated operation and increase load the database,
deterioration.
+
+Use the following logic:
+
+When data is deleted B found themselves fail (write), choose to wait for this
period of time and try again.Can choose to retry time exponentially, such as
first class 1 minute, the second for 10 minutes, 100 minutes for the third time.
+This decrease after operation, ensure database can cooling Down (Cool Down).
+
+### The Client reconnection registry
+
+When a registry downtime, other Client will receive events at the same time,
and to reconnect to another registry.The Client number is relatively more, will
be the impact of the registry.Avoid method can be a Client reconnection random
delay for 3 minutes, when the reconnection spread out.
