You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@dubbo.apache.org by il...@apache.org on 2019/04/16 02:39:40 UTC
[incubator-dubbo-website] branch asf-site updated: Translate Design
Principals (#310)
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 <ca...@126.com>
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.